tessl/npm-jsonld

A comprehensive JSON-LD Processor and API implementation in JavaScript for processing Linked Data in JSON format

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Event Handling

Name: tessl/npm-jsonld
Author: tessl

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.

Capabilities

Event Handlers

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

/**
 * Logs all events to console
 * @param event - The event object
 */
function logEventHandler(event);

/**
 * Logs only warning-level events to console
 * @param event - The event object
 */
function logWarningEventHandler(event);

/**
 * Safe event handler that prevents exceptions from stopping processing
 * @param event - The event object
 */
function safeEventHandler(event);

/**
 * Sets the default event handler for all operations
 * @param handler - The event handler function
 */
function setDefaultEventHandler(handler);

/**
 * Event handler that leaves events unhandled (no-op)
 * @param event - The event object
 */
function unhandledEventHandler(event);

/**
 * Strict event handler that throws exceptions for warnings and errors
 * @param event - The event object
 */
function strictEventHandler(event);

Usage Examples:

const jsonld = require('jsonld');

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

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

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

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

// Custom event handler
const customEventHandler = (event) => {
  if (event.level === 'warning') {
    console.warn('JSON-LD Warning:', event.message);
    console.warn('Details:', event.details);
  }
};

jsonld.setDefaultEventHandler(customEventHandler);

// Use specific handler for one operation
await jsonld.compact(doc, context, {
  eventHandler: customEventHandler
});

Event Structure

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

/**
 * Event object structure
 */
interface JsonLdEvent {
  /**
   * Event severity level
   */
  level: 'info' | 'warning' | 'error';
  
  /**
   * Event type/code identifier
   */
  code: string;
  
  /**
   * Human-readable event message
   */
  message: string;
  
  /**
   * Additional event-specific details
   */
  details?: any;
  
  /**
   * Context where the event occurred
   */
  context?: any;
}

/**
 * Event handler function type
 */
type EventHandler = (event: JsonLdEvent) => void;

Common Events

Events that may be emitted during JSON-LD processing.

Warning Events:

Deprecated Context: Use of deprecated context features
Lossy Processing: Data may be lost during processing
Invalid Value: Invalid values encountered but processing continues
Missing Context: Context could not be loaded but processing continues

Info Events:

Context Loaded: Remote context successfully loaded
Processing Step: Information about processing steps
Cache Hit: Context resolved from cache

Usage Examples:

// Monitor all events during processing
const eventMonitor = (event) => {
  console.log(`[${event.level.toUpperCase()}] ${event.code}: ${event.message}`);
  
  if (event.details) {
    console.log('Event details:', event.details);
  }
  
  // Track warnings for monitoring
  if (event.level === 'warning') {
    trackWarning(event.code, event.message);
  }
};

jsonld.setDefaultEventHandler(eventMonitor);

// Process document with event monitoring
const result = await jsonld.compact(doc, context);

Safe Mode Integration

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

Usage Examples:

// Safe mode with detailed event logging
const safeProcessor = async (doc, context) => {
  const events = [];
  
  const eventCollector = (event) => {
    events.push(event);
    
    // Still log warnings and errors
    if (event.level !== 'info') {
      console.log(`[${event.level}] ${event.message}`);
    }
  };
  
  try {
    const result = await jsonld.compact(doc, context, {
      safe: true,
      eventHandler: eventCollector
    });
    
    return {
      result,
      events,
      warnings: events.filter(e => e.level === 'warning'),
      errors: events.filter(e => e.level === 'error')
    };
  } catch (error) {
    return {
      result: null,
      error,
      events,
      warnings: events.filter(e => e.level === 'warning'),
      errors: events.filter(e => e.level === 'error')
    };
  }
};

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

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

if (errors.length > 0) {
  console.log(`Processing encountered ${errors.length} errors`);
}

Custom Event Handlers

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

Usage Examples:

// Metrics collection event handler
class MetricsEventHandler {
  constructor() {
    this.metrics = {
      warnings: 0,
      errors: 0,
      contextsLoaded: 0,
      cacheHits: 0
    };
  }
  
  handle(event) {
    // Count events by level
    if (event.level === 'warning') {
      this.metrics.warnings++;
    } else if (event.level === 'error') {
      this.metrics.errors++;
    }
    
    // Track specific event types
    switch (event.code) {
      case 'context loaded':
        this.metrics.contextsLoaded++;
        break;
      case 'cache hit':
        this.metrics.cacheHits++;
        break;
    }
  }
  
  getMetrics() {
    return {...this.metrics};
  }
  
  reset() {
    Object.keys(this.metrics).forEach(key => {
      this.metrics[key] = 0;
    });
  }
}

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

// Process documents
await jsonld.compact(doc1, context);
await jsonld.expand(doc2);

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

// Filtering event handler (only log specific events)
const filteredEventHandler = (event) => {
  // Only log warnings and errors
  if (event.level === 'warning' || event.level === 'error') {
    console.log(`[${event.level.toUpperCase()}] ${event.code}: ${event.message}`);
  }
  
  // Only log specific event codes
  const importantCodes = ['deprecated context', 'lossy processing', 'invalid value'];
  if (importantCodes.includes(event.code)) {
    console.log(`Important event: ${event.message}`);
  }
};

// Integration with external logging system
const loggerIntegrationHandler = (event) => {
  // Send to external logger
  logger.log({
    level: event.level,
    message: `JSON-LD ${event.code}: ${event.message}`,
    metadata: {
      code: event.code,
      details: event.details,
      context: event.context,
      timestamp: new Date().toISOString()
    }
  });
};

Event Handler Best Practices

Performance Considerations:

Keep event handlers lightweight as they're called frequently
Avoid synchronous I/O operations in event handlers
Consider using event filtering to reduce processing overhead

Error Handling:

Event handlers should not throw exceptions
Use try-catch within handlers to prevent disrupting JSON-LD processing
Consider using the safeEventHandler as a wrapper for custom handlers

Debugging:

Use logEventHandler during development for full visibility
Switch to logWarningEventHandler or filtered handlers in production
Collect events in safe mode for post-processing analysis

Usage Examples:

// Safe wrapper for custom event handlers
const makeSafeEventHandler = (handler) => {
  return (event) => {
    try {
      handler(event);
    } catch (error) {
      console.error('Event handler error:', error);
    }
  };
};

// Use safe wrapper
const safeCustomHandler = makeSafeEventHandler(customEventHandler);
jsonld.setDefaultEventHandler(safeCustomHandler);

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

jsonld.setDefaultEventHandler(
  isDevelopment 
    ? jsonld.logEventHandler 
    : jsonld.logWarningEventHandler
);

Types

/**
 * Event severity levels
 */
type EventLevel = 'info' | 'warning' | 'error';

/**
 * Common event codes
 */
type EventCode = 
  | 'deprecated context'
  | 'lossy processing'
  | 'invalid value'
  | 'missing context'
  | 'context loaded'
  | 'processing step'
  | 'cache hit'
  | string; // Additional custom codes

/**
 * Event handler options in JSON-LD operations
 */
interface EventHandlerOptions {
  /**
   * Custom event handler for this operation
   */
  eventHandler?: EventHandler;
}

/**
 * Built-in event handlers available
 */
interface EventHandlers {
  /**
   * Logs all events to console
   */
  logEventHandler: EventHandler;
  
  /**
   * Logs only warning-level events
   */
  logWarningEventHandler: EventHandler;
  
  /**
   * Safe event handler preventing exceptions
   */
  safeEventHandler: EventHandler;
  
  /**
   * No-op event handler
   */
  unhandledEventHandler: EventHandler;
  
  /**
   * Strict event handler that throws on warnings/errors
   */
  strictEventHandler: EventHandler;
}