0
# Document Loading
1

2
Extensible document loading system for fetching remote contexts and JSON-LD documents. The document loading system allows customization of how JSON-LD documents and contexts are retrieved from URLs, enabling caching, authentication, and other advanced scenarios.
3

4
## Capabilities
5

6
### Document Loader Property
7

8
The default document loader for external documents. This property can be get/set to customize document loading behavior.
9

10
```javascript { .api }
11
/**
12
 * Default document loader for external documents
13
 * @type {DocumentLoader}
14
 */
15
let documentLoader;
16
```
17

18
**Default Behavior:**
19
The default document loader throws an error indicating URL dereferencing is not implemented. You must set a custom loader or use one of the built-in loaders.
20

21
**Usage Examples:**
22

23
```javascript
24
const jsonld = require('jsonld');
25

26
// Get current document loader
27
const currentLoader = jsonld.documentLoader;
28

29
// Set custom document loader
30
jsonld.documentLoader = async (url, options) => {
31
  // Custom loading logic
32
  const response = await fetch(url);
33
  const document = await response.json();
34
  return {
35
    contextUrl: null,
36
    document: document,
37
    documentUrl: url
38
  };
39
};
40
```
41

42
### Get Document
43

44
Gets a remote JSON-LD document using the configured document loader.
45

46
```javascript { .api }
47
/**
48
 * Gets remote JSON-LD document using document loader
49
 * @param url - The URL to fetch
50
 * @param options - Optional configuration object
51
 * @returns Promise resolving to retrieved remote document
52
 */
53
function get(url, options);
54
```
55

56
**Parameters:**
57
- `url` (string): URL to fetch
58
- `options` (object, optional): Configuration options including custom documentLoader
59

60
**Returns:** Promise resolving to RemoteDocument object
61

62
**Usage Examples:**
63

64
```javascript
65
// Basic document retrieval
66
const remoteDoc = await jsonld.get('http://example.org/context.jsonld');
67
console.log(remoteDoc.document); // The loaded document
68
console.log(remoteDoc.documentUrl); // Final URL after redirects
69

70
// Get with custom loader for this call
71
const customLoader = async (url) => {
72
  // Custom logic
73
  return {
74
    contextUrl: null,
75
    document: {/* document content */},
76
    documentUrl: url
77
  };
78
};
79

80
const doc = await jsonld.get('http://example.org/doc', {
81
  documentLoader: customLoader
82
});
83
```
84

85
### Use Document Loader
86

87
Sets the default document loader to one of the built-in types with optional parameters.
88

89
```javascript { .api }
90
/**
91
 * Sets default document loader to built-in type
92
 * @param type - Document loader type ('node' or 'xhr')
93
 * @param ...params - Additional parameters for the loader
94
 */
95
function useDocumentLoader(type, ...params);
96
```
97

98
**Parameters:**
99
- `type` (string): Document loader type - 'node' for Node.js or 'xhr' for browser
100
- `params` (any[]): Additional parameters required by the specific loader
101

102
**Available Types:**
103
- `'node'`: Node.js HTTP/HTTPS document loader
104
- `'xhr'`: Browser XMLHttpRequest document loader
105

106
**Usage Examples:**
107

108
```javascript
109
// Use Node.js document loader (default in Node.js environment)
110
jsonld.useDocumentLoader('node');
111

112
// Use XHR document loader (for browser environments)
113
jsonld.useDocumentLoader('xhr');
114

115
// Use Node.js loader with custom options
116
jsonld.useDocumentLoader('node', {
117
  headers: {
118
    'User-Agent': 'MyApp/1.0'
119
  }
120
});
121
```
122

123
### Document Loaders Registry
124

125
Registry containing available built-in document loaders.
126

127
```javascript { .api }
128
/**
129
 * Registry of available document loaders
130
 */
131
const documentLoaders;
132
```
133

134
**Available Loaders:**
135
- `documentLoaders.node`: Node.js HTTP/HTTPS document loader factory
136
- `documentLoaders.xhr`: Browser XMLHttpRequest document loader factory
137

138
**Usage Examples:**
139

140
```javascript
141
// Get Node.js document loader factory
142
const nodeLoader = jsonld.documentLoaders.node;
143

144
// Create custom Node.js loader instance
145
const customNodeLoader = nodeLoader({
146
  headers: {
147
    'User-Agent': 'MyJsonLdApp/1.0',
148
    'Accept': 'application/ld+json, application/json'
149
  }
150
});
151

152
// Use the custom loader
153
jsonld.documentLoader = customNodeLoader;
154
```
155

156
### Custom Document Loaders
157

158
How to create and use custom document loaders for advanced scenarios like caching, authentication, or offline operation.
159

160
**Usage Examples:**
161

162
```javascript
163
// Pre-loaded contexts cache example
164
const CONTEXTS = {
165
  "http://schema.org": {
166
    "@context": {
167
      "name": "http://schema.org/name",
168
      "Person": "http://schema.org/Person"
169
    }
170
  },
171
  "http://example.org/context": {
172
    "@context": {
173
      "title": "http://purl.org/dc/terms/title"
174
    }
175
  }
176
};
177

178
// Custom loader with fallback to built-in loader
179
const nodeDocumentLoader = jsonld.documentLoaders.node();
180

181
const customLoader = async (url, options) => {
182
  // Check cache first
183
  if (url in CONTEXTS) {
184
    return {
185
      contextUrl: null,
186
      document: CONTEXTS[url],
187
      documentUrl: url
188
    };
189
  }
190
  
191
  // Fall back to default loader
192
  return nodeDocumentLoader(url, options);
193
};
194

195
jsonld.documentLoader = customLoader;
196

197
// Authentication example
198
const authenticatedLoader = async (url, options) => {
199
  const response = await fetch(url, {
200
    headers: {
201
      'Authorization': 'Bearer ' + getAuthToken(),
202
      'Accept': 'application/ld+json, application/json'
203
    }
204
  });
205
  
206
  if (!response.ok) {
207
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
208
  }
209
  
210
  const document = await response.json();
211
  return {
212
    contextUrl: null,
213
    document: document,
214
    documentUrl: response.url
215
  };
216
};
217

218
// Rate limiting example
219
class RateLimitedLoader {
220
  constructor(baseLoader, requestsPerSecond = 10) {
221
    this.baseLoader = baseLoader;
222
    this.interval = 1000 / requestsPerSecond;
223
    this.lastRequest = 0;
224
  }
225
  
226
  async load(url, options) {
227
    const now = Date.now();
228
    const timeSinceLastRequest = now - this.lastRequest;
229
    
230
    if (timeSinceLastRequest < this.interval) {
231
      await new Promise(resolve => 
232
        setTimeout(resolve, this.interval - timeSinceLastRequest)
233
      );
234
    }
235
    
236
    this.lastRequest = Date.now();
237
    return this.baseLoader(url, options);
238
  }
239
}
240

241
const rateLimitedLoader = new RateLimitedLoader(
242
  jsonld.documentLoaders.node(), 
243
  5 // 5 requests per second
244
);
245

246
jsonld.documentLoader = (url, options) => rateLimitedLoader.load(url, options);
247
```
248

249
## Types
250

251
```javascript { .api }
252
/**
253
 * Document loader function type
254
 */
255
type DocumentLoader = (url: string, options?: any) => Promise<RemoteDocument>;
256

257
/**
258
 * Remote document structure returned by document loaders
259
 */
260
interface RemoteDocument {
261
  /**
262
   * Context URL from HTTP Link header (optional)
263
   */
264
  contextUrl?: string;
265
  
266
  /**
267
   * The actual document that was loaded
268
   */
269
  document: any;
270
  
271
  /**
272
   * The actual document URL after redirects
273
   */
274
  documentUrl: string;
275
}
276

277
/**
278
 * Document loader factory function type
279
 */
280
type DocumentLoaderFactory = (options?: any) => DocumentLoader;
281

282
/**
283
 * Document loaders registry interface
284
 */
285
interface DocumentLoaders {
286
  /**
287
   * Node.js HTTP/HTTPS document loader factory
288
   */
289
  node: DocumentLoaderFactory;
290
  
291
  /**
292
   * Browser XMLHttpRequest document loader factory
293
   */
294
  xhr: DocumentLoaderFactory;
295
}
296

297
/**
298
 * Node.js document loader options
299
 */
300
interface NodeDocumentLoaderOptions {
301
  /**
302
   * HTTP headers to include in requests
303
   */
304
  headers?: Record<string, string>;
305
  
306
  /**
307
   * Maximum number of redirects to follow
308
   */
309
  maxRedirects?: number;
310
  
311
  /**
312
   * Request timeout in milliseconds
313
   */
314
  timeout?: number;
315
  
316
  /**
317
   * HTTPS agent options
318
   */
319
  httpsAgent?: any;
320
  
321
  /**
322
   * HTTP agent options
323
   */
324
  httpAgent?: any;
325
}
326

327
/**
328
 * XHR document loader options
329
 */
330
interface XhrDocumentLoaderOptions {
331
  /**
332
   * HTTP headers to include in requests
333
   */
334
  headers?: Record<string, string>;
335
  
336
  /**
337
   * Request timeout in milliseconds
338
   */
339
  timeout?: number;
340
  
341
  /**
342
   * Whether to include credentials in cross-origin requests
343
   */
344
  withCredentials?: boolean;
345
}
346
```