0
# Web Utilities
1

2
Web-related utilities for HTML escaping/unescaping and safe URI component encoding/decoding with error handling, essential for web applications and API development.
3

4
## Capabilities
5

6
### HTML Escaping
7

8
Escape HTML strings to prevent XSS attacks and ensure safe rendering.
9

10
```typescript { .api }
11
/**
12
 * Escape HTML string to prevent XSS
13
 * @param html - HTML string to escape
14
 * @returns Escaped HTML string
15
 */
16
function escape(html: string): string;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { escape } from "utility";
23

24
// Basic HTML escaping
25
const safe = escape('<script>alert("xss")</script>');
26
// Result: "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
27

28
// User input escaping
29
const userInput = escape('User said: "Hello & goodbye"');
30
// Result: "User said: &quot;Hello &amp; goodbye&quot;"
31

32
// Template usage
33
const template = `<div>${escape(userContent)}</div>`;
34
```
35

36
### HTML Unescaping
37

38
Unescape HTML strings back to original form with optional type specification.
39

40
```typescript { .api }
41
/**
42
 * Unescape HTML string back to original form
43
 * @param html - Escaped HTML string
44
 * @param type - Optional unescape type
45
 * @returns Unescaped HTML string
46
 */
47
function unescape(html: string, type?: string): string;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { unescape } from "utility";
54

55
// Basic HTML unescaping
56
const original = unescape("&lt;div&gt;Hello &amp; goodbye&lt;/div&gt;");
57
// Result: "<div>Hello & goodbye</div>"
58

59
// Quote unescaping
60
const quotes = unescape("He said &quot;Hello&quot;");
61
// Result: 'He said "Hello"'
62

63
// With type parameter
64
const typed = unescape("&amp;nbsp;", "html");
65
// Result depends on unescape library implementation
66
```
67

68
### Safe URI Component Encoding
69

70
Safe URI component encoding that won't throw errors on invalid input.
71

72
```typescript { .api }
73
/**
74
 * Safe encodeURIComponent that won't throw errors
75
 * @param text - Text to encode
76
 * @returns URL encoded string or original text if encoding fails
77
 */
78
function encodeURIComponent(text: string): string;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { encodeURIComponent } from "utility";
85

86
// Normal encoding
87
const encoded = encodeURIComponent("hello world");
88
// Result: "hello%20world"
89

90
// Special characters
91
const special = encodeURIComponent("user@example.com");
92
// Result: "user%40example.com"
93

94
// Invalid input (won't throw)
95
const invalid = encodeURIComponent("invalid\uD800");
96
// Result: "invalid\uD800" (returns original on error)
97

98
// Query parameter encoding
99
const params = `name=${encodeURIComponent(userName)}&email=${encodeURIComponent(userEmail)}`;
100
```
101

102
### Safe URI Component Decoding
103

104
Safe URI component decoding that won't throw errors on malformed input.
105

106
```typescript { .api }
107
/**
108
 * Safe decodeURIComponent that won't throw errors
109
 * @param encodeText - Encoded text to decode
110
 * @returns URL decoded string or original text if decoding fails
111
 */
112
function decodeURIComponent(encodeText: string): string;
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { decodeURIComponent } from "utility";
119

120
// Normal decoding
121
const decoded = decodeURIComponent("hello%20world");
122
// Result: "hello world"
123

124
// Email decoding
125
const email = decodeURIComponent("user%40example.com");
126
// Result: "user@example.com"
127

128
// Malformed input (won't throw)
129
const malformed = decodeURIComponent("invalid%");
130
// Result: "invalid%" (returns original on error)
131

132
// Query parameter parsing
133
function parseQuery(queryString: string): Record<string, string> {
134
  const params: Record<string, string> = {};
135
  const pairs = queryString.split('&');
136
  
137
  for (const pair of pairs) {
138
    const [key, value] = pair.split('=');
139
    if (key && value) {
140
      params[decodeURIComponent(key)] = decodeURIComponent(value);
141
    }
142
  }
143
  
144
  return params;
145
}
146

147
const query = parseQuery("name=John%20Doe&email=john%40example.com");
148
// Result: { name: "John Doe", email: "john@example.com" }
149
```