0
# Event Handling
1

2
Event handling system for debugging, monitoring, and safe mode operations. JSON-LD operations can emit various events during processing, and the library provides a comprehensive event handling system for logging, debugging, and implementing custom processing behavior.
3

4
## Capabilities
5

6
### Event Handlers
7

8
The library provides several built-in event handlers for different use cases.
9

10
```javascript { .api }
11
/**
12
 * Logs all events to console
13
 * @param event - The event object
14
 */
15
function logEventHandler(event);
16

17
/**
18
 * Logs only warning-level events to console
19
 * @param event - The event object
20
 */
21
function logWarningEventHandler(event);
22

23
/**
24
 * Safe event handler that prevents exceptions from stopping processing
25
 * @param event - The event object
26
 */
27
function safeEventHandler(event);
28

29
/**
30
 * Sets the default event handler for all operations
31
 * @param handler - The event handler function
32
 */
33
function setDefaultEventHandler(handler);
34

35
/**
36
 * Event handler that leaves events unhandled (no-op)
37
 * @param event - The event object
38
 */
39
function unhandledEventHandler(event);
40

41
/**
42
 * Strict event handler that throws exceptions for warnings and errors
43
 * @param event - The event object
44
 */
45
function strictEventHandler(event);
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
const jsonld = require('jsonld');
52

53
// Use log event handler to see all events
54
jsonld.setDefaultEventHandler(jsonld.logEventHandler);
55

56
// Use warning-only event handler for production
57
jsonld.setDefaultEventHandler(jsonld.logWarningEventHandler);
58

59
// Use safe event handler to prevent crashes
60
jsonld.setDefaultEventHandler(jsonld.safeEventHandler);
61

62
// Use strict event handler to fail fast on warnings/errors
63
jsonld.setDefaultEventHandler(jsonld.strictEventHandler);
64

65
// Custom event handler
66
const customEventHandler = (event) => {
67
  if (event.level === 'warning') {
68
    console.warn('JSON-LD Warning:', event.message);
69
    console.warn('Details:', event.details);
70
  }
71
};
72

73
jsonld.setDefaultEventHandler(customEventHandler);
74

75
// Use specific handler for one operation
76
await jsonld.compact(doc, context, {
77
  eventHandler: customEventHandler
78
});
79
```
80

81
### Event Structure
82

83
Events emitted by JSON-LD operations follow a consistent structure.
84

85
```javascript { .api }
86
/**
87
 * Event object structure
88
 */
89
interface JsonLdEvent {
90
  /**
91
   * Event severity level
92
   */
93
  level: 'info' | 'warning' | 'error';
94
  
95
  /**
96
   * Event type/code identifier
97
   */
98
  code: string;
99
  
100
  /**
101
   * Human-readable event message
102
   */
103
  message: string;
104
  
105
  /**
106
   * Additional event-specific details
107
   */
108
  details?: any;
109
  
110
  /**
111
   * Context where the event occurred
112
   */
113
  context?: any;
114
}
115

116
/**
117
 * Event handler function type
118
 */
119
type EventHandler = (event: JsonLdEvent) => void;
120
```
121

122
### Common Events
123

124
Events that may be emitted during JSON-LD processing.
125

126
**Warning Events:**
127
- **Deprecated Context**: Use of deprecated context features
128
- **Lossy Processing**: Data may be lost during processing
129
- **Invalid Value**: Invalid values encountered but processing continues
130
- **Missing Context**: Context could not be loaded but processing continues
131

132
**Info Events:**
133
- **Context Loaded**: Remote context successfully loaded
134
- **Processing Step**: Information about processing steps
135
- **Cache Hit**: Context resolved from cache
136

137
**Usage Examples:**
138

139
```javascript
140
// Monitor all events during processing
141
const eventMonitor = (event) => {
142
  console.log(`[${event.level.toUpperCase()}] ${event.code}: ${event.message}`);
143
  
144
  if (event.details) {
145
    console.log('Event details:', event.details);
146
  }
147
  
148
  // Track warnings for monitoring
149
  if (event.level === 'warning') {
150
    trackWarning(event.code, event.message);
151
  }
152
};
153

154
jsonld.setDefaultEventHandler(eventMonitor);
155

156
// Process document with event monitoring
157
const result = await jsonld.compact(doc, context);
158
```
159

160
### Safe Mode Integration
161

162
Event handlers are particularly important when using safe mode, as they provide visibility into potential issues.
163

164
**Usage Examples:**
165

166
```javascript
167
// Safe mode with detailed event logging
168
const safeProcessor = async (doc, context) => {
169
  const events = [];
170
  
171
  const eventCollector = (event) => {
172
    events.push(event);
173
    
174
    // Still log warnings and errors
175
    if (event.level !== 'info') {
176
      console.log(`[${event.level}] ${event.message}`);
177
    }
178
  };
179
  
180
  try {
181
    const result = await jsonld.compact(doc, context, {
182
      safe: true,
183
      eventHandler: eventCollector
184
    });
185
    
186
    return {
187
      result,
188
      events,
189
      warnings: events.filter(e => e.level === 'warning'),
190
      errors: events.filter(e => e.level === 'error')
191
    };
192
  } catch (error) {
193
    return {
194
      result: null,
195
      error,
196
      events,
197
      warnings: events.filter(e => e.level === 'warning'),
198
      errors: events.filter(e => e.level === 'error')
199
    };
200
  }
201
};
202

203
// Use safe processor
204
const {result, warnings, errors} = await safeProcessor(doc, context);
205

206
if (warnings.length > 0) {
207
  console.log(`Processing completed with ${warnings.length} warnings`);
208
}
209

210
if (errors.length > 0) {
211
  console.log(`Processing encountered ${errors.length} errors`);
212
}
213
```
214

215
### Custom Event Handlers
216

217
Create custom event handlers for specific use cases like metrics collection, filtering, or integration with logging systems.
218

219
**Usage Examples:**
220

221
```javascript
222
// Metrics collection event handler
223
class MetricsEventHandler {
224
  constructor() {
225
    this.metrics = {
226
      warnings: 0,
227
      errors: 0,
228
      contextsLoaded: 0,
229
      cacheHits: 0
230
    };
231
  }
232
  
233
  handle(event) {
234
    // Count events by level
235
    if (event.level === 'warning') {
236
      this.metrics.warnings++;
237
    } else if (event.level === 'error') {
238
      this.metrics.errors++;
239
    }
240
    
241
    // Track specific event types
242
    switch (event.code) {
243
      case 'context loaded':
244
        this.metrics.contextsLoaded++;
245
        break;
246
      case 'cache hit':
247
        this.metrics.cacheHits++;
248
        break;
249
    }
250
  }
251
  
252
  getMetrics() {
253
    return {...this.metrics};
254
  }
255
  
256
  reset() {
257
    Object.keys(this.metrics).forEach(key => {
258
      this.metrics[key] = 0;
259
    });
260
  }
261
}
262

263
// Use metrics handler
264
const metricsHandler = new MetricsEventHandler();
265
jsonld.setDefaultEventHandler(event => metricsHandler.handle(event));
266

267
// Process documents
268
await jsonld.compact(doc1, context);
269
await jsonld.expand(doc2);
270

271
// Check metrics
272
console.log('Processing metrics:', metricsHandler.getMetrics());
273

274
// Filtering event handler (only log specific events)
275
const filteredEventHandler = (event) => {
276
  // Only log warnings and errors
277
  if (event.level === 'warning' || event.level === 'error') {
278
    console.log(`[${event.level.toUpperCase()}] ${event.code}: ${event.message}`);
279
  }
280
  
281
  // Only log specific event codes
282
  const importantCodes = ['deprecated context', 'lossy processing', 'invalid value'];
283
  if (importantCodes.includes(event.code)) {
284
    console.log(`Important event: ${event.message}`);
285
  }
286
};
287

288
// Integration with external logging system
289
const loggerIntegrationHandler = (event) => {
290
  // Send to external logger
291
  logger.log({
292
    level: event.level,
293
    message: `JSON-LD ${event.code}: ${event.message}`,
294
    metadata: {
295
      code: event.code,
296
      details: event.details,
297
      context: event.context,
298
      timestamp: new Date().toISOString()
299
    }
300
  });
301
};
302
```
303

304
### Event Handler Best Practices
305

306
**Performance Considerations:**
307
- Keep event handlers lightweight as they're called frequently
308
- Avoid synchronous I/O operations in event handlers
309
- Consider using event filtering to reduce processing overhead
310

311
**Error Handling:**
312
- Event handlers should not throw exceptions
313
- Use try-catch within handlers to prevent disrupting JSON-LD processing
314
- Consider using the `safeEventHandler` as a wrapper for custom handlers
315

316
**Debugging:**
317
- Use `logEventHandler` during development for full visibility
318
- Switch to `logWarningEventHandler` or filtered handlers in production
319
- Collect events in safe mode for post-processing analysis
320

321
**Usage Examples:**
322

323
```javascript
324
// Safe wrapper for custom event handlers
325
const makeSafeEventHandler = (handler) => {
326
  return (event) => {
327
    try {
328
      handler(event);
329
    } catch (error) {
330
      console.error('Event handler error:', error);
331
    }
332
  };
333
};
334

335
// Use safe wrapper
336
const safeCustomHandler = makeSafeEventHandler(customEventHandler);
337
jsonld.setDefaultEventHandler(safeCustomHandler);
338

339
// Development vs production event handling
340
const isDevelopment = process.env.NODE_ENV === 'development';
341

342
jsonld.setDefaultEventHandler(
343
  isDevelopment 
344
    ? jsonld.logEventHandler 
345
    : jsonld.logWarningEventHandler
346
);
347
```
348

349
## Types
350

351
```javascript { .api }
352
/**
353
 * Event severity levels
354
 */
355
type EventLevel = 'info' | 'warning' | 'error';
356

357
/**
358
 * Common event codes
359
 */
360
type EventCode = 
361
  | 'deprecated context'
362
  | 'lossy processing'
363
  | 'invalid value'
364
  | 'missing context'
365
  | 'context loaded'
366
  | 'processing step'
367
  | 'cache hit'
368
  | string; // Additional custom codes
369

370
/**
371
 * Event handler options in JSON-LD operations
372
 */
373
interface EventHandlerOptions {
374
  /**
375
   * Custom event handler for this operation
376
   */
377
  eventHandler?: EventHandler;
378
}
379

380
/**
381
 * Built-in event handlers available
382
 */
383
interface EventHandlers {
384
  /**
385
   * Logs all events to console
386
   */
387
  logEventHandler: EventHandler;
388
  
389
  /**
390
   * Logs only warning-level events
391
   */
392
  logWarningEventHandler: EventHandler;
393
  
394
  /**
395
   * Safe event handler preventing exceptions
396
   */
397
  safeEventHandler: EventHandler;
398
  
399
  /**
400
   * No-op event handler
401
   */
402
  unhandledEventHandler: EventHandler;
403
  
404
  /**
405
   * Strict event handler that throws on warnings/errors
406
   */
407
  strictEventHandler: EventHandler;
408
}
409
```