0
# URL Utilities
1

2
URL manipulation and parsing utilities for IRI processing in JSON-LD operations. These utilities provide comprehensive URL/IRI handling capabilities including parsing, base resolution, and normalization.
3

4
## Capabilities
5

6
### URL Parsing
7

8
Parse URLs using different levels of detail with built-in parsers.
9

10
```javascript { .api }
11
/**
12
 * Parse a URL string using specified parser
13
 * @param str - The URL string to parse
14
 * @param parser - Parser type: 'simple' or 'full' (default: 'full')
15
 * @returns Parsed URL object
16
 */
17
function parse(str, parser);
18
```
19

20
**Parameters:**
21
- `str` (string): URL string to parse
22
- `parser` (string, optional): Parser type - 'simple' or 'full' (default: 'full')
23

24
**Usage Examples:**
25

26
```javascript
27
const jsonld = require('jsonld');
28

29
// Full URL parsing (default)
30
const fullParsed = jsonld.url.parse('https://user:pass@example.org:8080/path/to/resource?query=value#fragment');
31
// Result: {
32
//   href: 'https://user:pass@example.org:8080/path/to/resource?query=value#fragment',
33
//   protocol: 'https:',
34
//   scheme: 'https',
35
//   authority: 'user:pass@example.org:8080',
36
//   auth: 'user:pass',
37
//   user: 'user',
38
//   password: 'pass',
39
//   hostname: 'example.org',
40
//   port: '8080',
41
//   path: '/path/to/resource',
42
//   directory: '/path/to/',
43
//   file: 'resource',
44
//   query: 'query=value',
45
//   fragment: 'fragment'
46
// }
47

48
// Simple URL parsing
49
const simpleParsed = jsonld.url.parse('https://example.org/path?query#fragment', 'simple');
50
// Result: {
51
//   href: 'https://example.org/path?query#fragment',
52
//   scheme: 'https',
53
//   authority: 'example.org',
54
//   path: '/path',
55
//   query: 'query',
56
//   fragment: 'fragment'
57
// }
58

59
// Parse relative URLs
60
const relativeParsed = jsonld.url.parse('/path/to/resource');
61
// Result: { path: '/path/to/resource', ... }
62
```
63

64
### URL Parsers
65

66
Access to the built-in URL parsing configurations.
67

68
```javascript { .api }
69
/**
70
 * Available URL parsers with their configurations
71
 */
72
const parsers;
73
```
74

75
**Available Parsers:**
76
- `parsers.simple`: Basic RFC 3986 parsing with essential components
77
- `parsers.full`: Comprehensive parsing with all URL components
78

79
**Usage Examples:**
80

81
```javascript
82
// Access parser configurations
83
const simpleParser = jsonld.url.parsers.simple;
84
console.log('Simple parser keys:', simpleParser.keys);
85
// Output: ['href', 'scheme', 'authority', 'path', 'query', 'fragment']
86

87
const fullParser = jsonld.url.parsers.full;
88
console.log('Full parser keys:', fullParser.keys);
89
// Output: ['href', 'protocol', 'scheme', 'authority', 'auth', 'user', 'password', 
90
//          'hostname', 'port', 'path', 'directory', 'file', 'query', 'fragment']
91

92
// Use parser regex directly
93
const customMatch = fullParser.regex.exec('https://example.org/path');
94
```
95

96
### Base IRI Resolution
97

98
Resolve relative IRIs against a base IRI.
99

100
```javascript { .api }
101
/**
102
 * Prepends a base IRI to a relative IRI
103
 * @param base - The base IRI
104
 * @param iri - The IRI to resolve (may be relative)
105
 * @returns Absolute IRI
106
 */
107
function prependBase(base, iri);
108
```
109

110
**Parameters:**
111
- `base` (string): Base IRI for resolution
112
- `iri` (string): IRI to resolve (absolute or relative)
113

114
**Usage Examples:**
115

116
```javascript
117
// Resolve relative IRI against base
118
const resolved = jsonld.url.prependBase('https://example.org/path/', 'resource.jsonld');
119
// Result: 'https://example.org/path/resource.jsonld'
120

121
// Resolve relative path
122
const resolved2 = jsonld.url.prependBase('https://example.org/docs/', '../contexts/schema.jsonld');
123
// Result: 'https://example.org/contexts/schema.jsonld'
124

125
// Absolute IRI remains unchanged
126
const resolved3 = jsonld.url.prependBase('https://example.org/', 'https://schema.org/Person');
127
// Result: 'https://schema.org/Person'
128

129
// Handle fragment identifiers
130
const resolved4 = jsonld.url.prependBase('https://example.org/doc', '#section1');
131
// Result: 'https://example.org/doc#section1'
132
```
133

134
### Base IRI Removal
135

136
Remove a base IRI from an absolute IRI to create a relative reference.
137

138
```javascript { .api }
139
/**
140
 * Removes a base IRI from an IRI, making it relative if possible
141
 * @param base - The base IRI to remove
142
 * @param iri - The absolute IRI
143
 * @returns Relative IRI if possible, otherwise the original IRI
144
 */
145
function removeBase(base, iri);
146
```
147

148
**Parameters:**
149
- `base` (string): Base IRI to remove
150
- `iri` (string): Absolute IRI to make relative
151

152
**Usage Examples:**
153

154
```javascript
155
// Make IRI relative to base
156
const relative = jsonld.url.removeBase('https://example.org/docs/', 'https://example.org/docs/schema.jsonld');
157
// Result: 'schema.jsonld'
158

159
// Remove base from path
160
const relative2 = jsonld.url.removeBase('https://example.org/', 'https://example.org/contexts/person.jsonld');
161
// Result: 'contexts/person.jsonld'
162

163
// Different domain - no change
164
const relative3 = jsonld.url.removeBase('https://example.org/', 'https://schema.org/Person');
165
// Result: 'https://schema.org/Person' (unchanged)
166

167
// Fragment handling
168
const relative4 = jsonld.url.removeBase('https://example.org/doc', 'https://example.org/doc#section1');
169
// Result: '#section1'
170
```
171

172
### Path Normalization
173

174
Normalize URL paths by removing dot segments according to RFC 3986.
175

176
```javascript { .api }
177
/**
178
 * Removes dot segments from a URL path
179
 * @param path - The path to normalize
180
 * @returns Normalized path with dot segments removed
181
 */
182
function removeDotSegments(path);
183
```
184

185
**Parameters:**
186
- `path` (string): URL path to normalize
187

188
**Usage Examples:**
189

190
```javascript
191
// Remove single dot segments
192
const normalized1 = jsonld.url.removeDotSegments('/a/b/c/./../../g');
193
// Result: '/a/g'
194

195
// Remove double dot segments
196
const normalized2 = jsonld.url.removeDotSegments('/a/b/c/../d/e/../f');
197
// Result: '/a/b/d/f'
198

199
// Handle leading dots
200
const normalized3 = jsonld.url.removeDotSegments('../../../g');
201
// Result: 'g'
202

203
// Complex path normalization
204
const normalized4 = jsonld.url.removeDotSegments('/a/b/./c/../d/./e/../../f/g');
205
// Result: '/a/f/g'
206
```
207

208
### URL Type Checking
209

210
Check if URLs are absolute or relative.
211

212
```javascript { .api }
213
/**
214
 * Checks if a URL is absolute
215
 * @param v - The URL to check  
216
 * @returns true if URL is absolute
217
 */
218
function isAbsolute(v);
219

220
/**
221
 * Checks if a URL is relative
222
 * @param v - The URL to check
223
 * @returns true if URL is relative
224
 */
225
function isRelative(v);
226
```
227

228
**Usage Examples:**
229

230
```javascript
231
// Check absolute URLs
232
const isAbs1 = jsonld.url.isAbsolute('https://example.org/path');
233
// Result: true
234

235
const isAbs2 = jsonld.url.isAbsolute('/path/to/resource');
236
// Result: false
237

238
const isAbs3 = jsonld.url.isAbsolute('mailto:user@example.org');
239
// Result: true
240

241
// Check relative URLs
242
const isRel1 = jsonld.url.isRelative('./resource.jsonld');
243
// Result: true
244

245
const isRel2 = jsonld.url.isRelative('../contexts/schema.jsonld');
246
// Result: true
247

248
const isRel3 = jsonld.url.isRelative('https://example.org/');
249
// Result: false
250
```
251

252
### Complete URL Processing Example
253

254
Comprehensive example showing URL utility usage in JSON-LD context processing.
255

256
**Usage Examples:**
257

258
```javascript
259
// URL processing pipeline for JSON-LD contexts
260
const processContextUrl = (baseUrl, contextRef) => {
261
  console.log('Base URL:', baseUrl);
262
  console.log('Context reference:', contextRef);
263
  
264
  // Check if context reference is absolute
265
  if (jsonld.url.isAbsolute(contextRef)) {
266
    console.log('Context is absolute URL');
267
    return contextRef;
268
  }
269
  
270
  // Resolve relative context against base
271
  const resolvedUrl = jsonld.url.prependBase(baseUrl, contextRef);
272
  console.log('Resolved URL:', resolvedUrl);
273
  
274
  // Parse the resolved URL
275
  const parsed = jsonld.url.parse(resolvedUrl);
276
  console.log('Parsed components:', {
277
    scheme: parsed.scheme,
278
    hostname: parsed.hostname,
279
    path: parsed.path,
280
    query: parsed.query,
281
    fragment: parsed.fragment
282
  });
283
  
284
  // Normalize the path
285
  if (parsed.path) {
286
    const normalizedPath = jsonld.url.removeDotSegments(parsed.path);
287
    console.log('Normalized path:', normalizedPath);
288
  }
289
  
290
  return resolvedUrl;
291
};
292

293
// Example usage
294
const baseUrl = 'https://example.org/documents/person.jsonld';
295
const contextRef = '../contexts/schema.jsonld';
296
const finalUrl = processContextUrl(baseUrl, contextRef);
297
// Result: 'https://example.org/contexts/schema.jsonld'
298

299
// URL manipulation for JSON-LD compaction
300
const makeRelativeIfPossible = (baseUrl, targetUrl) => {
301
  if (jsonld.url.isAbsolute(targetUrl)) {
302
    // Try to make it relative
303
    const relative = jsonld.url.removeBase(baseUrl, targetUrl);
304
    
305
    // Check if it's actually relative now
306
    if (jsonld.url.isRelative(relative)) {
307
      console.log(`Made relative: ${targetUrl} -> ${relative}`);
308
      return relative;
309
    }
310
  }
311
  
312
  return targetUrl;
313
};
314
```
315

316
## Types
317

318
```javascript { .api }
319
/**
320
 * Simple URL parser result
321
 */
322
interface SimpleUrlParts {
323
  href: string;
324
  scheme: string | null;
325
  authority: string | null;
326
  path: string;
327
  query: string | null;
328
  fragment: string | null;
329
}
330

331
/**
332
 * Full URL parser result
333
 */
334
interface FullUrlParts extends SimpleUrlParts {
335
  protocol: string | null;
336
  auth: string | null;
337
  user: string | null;
338
  password: string | null;
339
  hostname: string | null;
340
  port: string | null;
341
  directory: string | null;
342
  file: string | null;
343
}
344

345
/**
346
 * URL parser configuration
347
 */
348
interface UrlParser {
349
  keys: string[];
350
  regex: RegExp;
351
}
352

353
/**
354
 * Available URL parsers
355
 */
356
interface UrlParsers {
357
  simple: UrlParser;
358
  full: UrlParser;
359
}
360

361
/**
362
 * URL utilities interface
363
 */
364
interface UrlUtilities {
365
  parse(str: string, parser?: 'simple' | 'full'): SimpleUrlParts | FullUrlParts;
366
  prependBase(base: string, iri: string): string;
367
  removeBase(base: string, iri: string): string;
368
  removeDotSegments(path: string): string;
369
  isAbsolute(v: string): boolean;
370
  isRelative(v: string): boolean;
371
  parsers: UrlParsers;
372
}
373
```