0
# URL Processing
1

2
URL templating and transformation utilities for building dynamic URLs with parameter substitution, query string handling, and URL parsing.
3

4
## Capabilities
5

6
### URL Templating
7

8
Core URL templating function that supports parameter substitution and transformations.
9

10
```javascript { .api }
11
/**
12
 * Process URL template with parameters and transformations
13
 * @param url - URL template string
14
 * @param params - Parameters for substitution
15
 * @returns Processed URL string
16
 */
17
function $url(url: string, params?: object): string;
18

19
/**
20
 * Process URL template with options object
21
 * @param options - URL options including url, params, and other settings
22
 * @returns Processed URL string
23
 */
24
function $url(options: UrlOptions): string;
25

26
interface UrlOptions {
27
  url: string;
28
  params?: object;
29
  root?: string;
30
}
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
// Basic URL templating
37
const url = this.$url('/api/users/{id}', {id: 123});
38
// Result: '/api/users/123'
39

40
// Optional parameters with braces
41
const url = this.$url('/api/users{/id}', {id: 123});
42
// Result: '/api/users/123'
43

44
const url = this.$url('/api/users{/id}', {});
45
// Result: '/api/users'
46

47
// With query parameters
48
const url = this.$url('/api/users', {page: 1, limit: 10});
49
// Result: '/api/users?page=1&limit=10'
50

51
// Using options object
52
const url = this.$url({
53
  url: '/api/users/{id}',
54
  params: {id: 123, active: true},
55
  root: 'https://api.example.com'
56
});
57
// Result: 'https://api.example.com/api/users/123?active=true'
58
```
59

60
### Parameter Encoding
61

62
Encode object parameters into URL query string format.
63

64
```javascript { .api }
65
/**
66
 * Encode an object into URL parameter string
67
 * @param obj - Object to encode as parameters
68
 * @returns URL-encoded parameter string
69
 */
70
function $url.params(obj: object): string;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
// Simple parameters
77
const params = this.$url.params({name: 'John', age: 30});
78
// Result: 'name=John&age=30'
79

80
// Array parameters
81
const params = this.$url.params({tags: ['javascript', 'vue', 'http']});
82
// Result: 'tags[]=javascript&tags[]=vue&tags[]=http'
83

84
// Nested object parameters
85
const params = this.$url.params({
86
  user: {name: 'John', email: 'john@example.com'},
87
  active: true
88
});
89
// Result: 'user[name]=John&user[email]=john%40example.com&active=true'
90

91
// Function values (called at encode time)
92
const params = this.$url.params({
93
  timestamp: () => Date.now(),
94
  random: Math.random
95
});
96
// Result: 'timestamp=1609459200000&random=0.123456789'
97

98
// Null values become empty strings
99
const params = this.$url.params({name: 'John', city: null});
100
// Result: 'name=John&city='
101
```
102

103
### URL Parsing
104

105
Parse a URL string into its component parts.
106

107
```javascript { .api }
108
/**
109
 * Parse a URL and return its components
110
 * @param url - URL string to parse
111
 * @returns Object with URL components
112
 */
113
function $url.parse(url: string): UrlComponents;
114

115
interface UrlComponents {
116
  /** Complete URL */
117
  href: string;
118
  /** Protocol (http, https, etc.) */
119
  protocol: string;
120
  /** Port number */
121
  port: string;
122
  /** Host with port */
123
  host: string;
124
  /** Hostname without port */
125
  hostname: string;
126
  /** Path portion */
127
  pathname: string;
128
  /** Query string without leading ? */
129
  search: string;  
130
  /** Hash fragment without leading # */
131
  hash: string;
132
}
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
const components = this.$url.parse('https://api.example.com:8080/users?page=1#section');
139

140
console.log(components.protocol); // 'https'
141
console.log(components.hostname); // 'api.example.com'
142
console.log(components.port);     // '8080'
143
console.log(components.host);     // 'api.example.com:8080'
144
console.log(components.pathname); // '/users'
145
console.log(components.search);   // 'page=1'
146
console.log(components.hash);     // 'section'
147
console.log(components.href);     // 'https://api.example.com:8080/users?page=1#section'
148

149
// Relative URL
150
const components = this.$url.parse('/api/users?active=true');
151
console.log(components.pathname); // '/api/users'
152
console.log(components.search);   // 'active=true'
153
console.log(components.protocol); // ''
154
console.log(components.hostname); // ''
155
```
156

157
### Global URL Configuration
158

159
Configure default URL options and transformations.
160

161
```javascript { .api }
162
// Default URL options
163
Vue.url.options: UrlOptions;
164

165
// URL transformation functions
166
Vue.url.transform: {
167
  template: Function;
168
  query: Function;
169
  root: Function;
170
};
171

172
// URL transformation pipeline
173
Vue.url.transforms: string[];
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
// Set global root URL
180
Vue.url.options.root = 'https://api.example.com';
181

182
// All URL calls will now use this root
183
const url = this.$url('/users'); 
184
// Result: 'https://api.example.com/users'
185

186
// Set default parameters
187
Vue.url.options.params = {version: 'v1'};
188

189
const url = this.$url('/users');
190
// Result: 'https://api.example.com/users?version=v1'
191

192
// Custom URL transformation
193
Vue.url.transforms.push('custom');
194
Vue.url.transform.custom = function(options, next) {
195
  // Add timestamp to all URLs
196
  options.params = options.params || {};
197
  options.params._t = Date.now();
198
  return next(options);
199
};
200
```
201

202
### URL Template Syntax
203

204
Vue Resource supports URI template syntax for flexible URL construction.
205

206
**Template Patterns:**
207

208
```javascript
209
// Basic parameter substitution
210
'/users/{id}'          // Required parameter
211
'/users/{id}/posts'    // Multiple parameters
212

213
// Optional parameters (with braces)
214
'/users{/id}'          // Optional parameter
215
'/users{/id}{/action}' // Multiple optional parameters
216

217
// Query parameters (automatically added)
218
'/users' + {page: 1, limit: 10} // Results in '/users?page=1&limit=10'
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
// Required parameters
225
this.$url('/users/{id}', {id: 123});
226
// Result: '/users/123'
227

228
this.$url('/users/{id}', {}); 
229
// Error: Missing required parameter 'id'
230

231
// Optional parameters
232
this.$url('/users{/id}', {id: 123});
233
// Result: '/users/123'
234

235
this.$url('/users{/id}', {});
236
// Result: '/users'
237

238
// Multiple optional parameters
239
this.$url('/users{/id}{/action}', {id: 123});
240
// Result: '/users/123'
241

242
this.$url('/users{/id}{/action}', {id: 123, action: 'edit'});
243
// Result: '/users/123/edit'
244

245
// Mixed required and optional
246
this.$url('/api/{version}/users{/id}', {version: 'v1', id: 123});
247
// Result: '/api/v1/users/123'
248

249
// Unused parameters become query string
250
this.$url('/users/{id}', {id: 123, active: true, page: 1});
251
// Result: '/users/123?active=true&page=1'
252
```
253

254
## Types
255

256
```javascript { .api }
257
interface UrlOptions {
258
  /** URL template string */
259
  url: string;
260
  /** Parameters for substitution and query string */
261
  params?: object;
262
  /** Root URL to prepend */
263
  root?: string;
264
}
265

266
interface UrlComponents {
267
  /** Complete URL */
268
  href: string;
269
  /** Protocol (http, https, etc.) without trailing colon */
270
  protocol: string;
271
  /** Port number as string */
272
  port: string;
273
  /** Host including port */
274
  host: string;
275
  /** Hostname without port */
276
  hostname: string;
277
  /** Path portion starting with / */
278
  pathname: string;
279
  /** Query string without leading ? */
280
  search: string;
281
  /** Hash fragment without leading # */
282
  hash: string;
283
}
284

285
interface UrlTransform {
286
  /** Template parameter substitution */
287
  template: (options: UrlOptions, next: Function) => UrlOptions;
288
  /** Query string processing */
289
  query: (options: UrlOptions, next: Function) => UrlOptions;  
290
  /** Root URL prepending */
291
  root: (options: UrlOptions, next: Function) => UrlOptions;
292
}
293
```