Event updates and add safe mode.

- Add `safe` flag to call a special safe mode event handler.
- Update events API and usage.
- Add `hasEventHandler` for call site optimization.
- Update handlers.

Author: davidlehn

lib/events.js

@@ -16,7 +16,24 @@ const {
 const api = {};
 module.exports = api;
 
-let _defaultEventHandler = [];
+// default handler, store as null or an array
+// exposed to allow fast external pre-handleEvent() checks
+api.defaultEventHandler = null;
+
+/**
+ * Check if event handler is in use in options or by default.
+ *
+ * This call is used to avoid building event structures and calling the main
+ * handleEvent() call. It checks if safe mode is on, an event handler is in the
+ * processing options, or a default handler was set.
+ *
+ * @param {object} options - processing options:
+ *   {boolean} [safe] - flag for Safe Mode.
+ *   {function|object|array} [eventHandler] - an event handler.
+ */
+api.hasEventHandler = options => {
+  return options.safe || options.eventHandler || api.defaultEventHandler;
+};
 
 /**
  * Handle an event.
@@ -28,9 +45,6 @@ let _defaultEventHandler = [];
  * handlers should process the event as appropriate. The 'next()' function
  * should be called to let the next handler process the event.
  *
- * The final default handler will use 'console.warn' for events of level
- * 'warning'.
- *
  * @param {object} event - event structure:
  *   {string} code - event code
  *   {string} level - severity level, one of: ['warning']
@@ -43,8 +57,10 @@ api.handleEvent = ({
   options
 }) => {
   const handlers = [].concat(
+    // priority is safe mode handler, options handler, then default handler
+    options.safe ? api.safeModeEventHandler : [],
     options.eventHandler ? _asArray(options.eventHandler) : [],
-    ..._defaultEventHandler
+    api.defaultEventHandler ? api.defaultEventHandler : []
   );
   _handle({event, handlers});
 };
@@ -78,64 +94,54 @@ function _handle({event, handlers}) {
   return doNext;
 }
 
-// logs all events and continues
-api.logEventHandler = function({event, next}) {
-  console.warn(`EVENT: ${event.message}`, {
-    code: event.code,
-    level: event.level,
-    details: event.details
-  });
+// safe handler that rejects unsafe warning conditions
+api.safeModeEventHandler = function({event, next}) {
+  // fail on all unsafe warnings
+  if(event.level === 'warning' && event.tags.includes('unsafe')) {
+    throw new JsonLdError(
+      'Safe mode violation.',
+      'jsonld.SafeModeViolationEvent',
+      {event}
+    );
+  }
   next();
 };
 
-// fallback to throw errors for any unhandled events
-api.unhandledEventHandler = function({event}) {
-  throw new JsonLdError(
-    'No handler for event.',
-    'jsonld.UnhandledEvent',
-    {event});
+// strict handler that rejects all warning conditions
+api.strictModeEventHandler = function({event, next}) {
+  // fail on all warnings
+  if(event.level === 'warning') {
+    throw new JsonLdError(
+      'Strict mode violation.',
+      'jsonld.StrictModeViolationEvent',
+      {event}
+    );
+  }
+  next();
 };
 
-// throw with event details
-api.throwUnacceptableEventHandler = function({event}) {
-  throw new JsonLdError(
-    'Unacceptable event occurred.',
-    'jsonld.UnacceptableEvent',
-    {event});
+// logs all events and continues
+api.logEventHandler = function({event, next}) {
+  console.log(`EVENT: ${event.message}`, {event});
+  next();
 };
 
 // log 'warning' level events
-api.logWarningEventHandler = function({event}) {
+api.logWarningEventHandler = function({event, next}) {
   if(event.level === 'warning') {
-    console.warn(`WARNING: ${event.message}`, {
-      code: event.code,
-      details: event.details
-    });
+    console.warn(`WARNING: ${event.message}`, {event});
   }
+  next();
 };
 
-// strict handler that rejects warning conditions
-api.strictModeEventHandler = [
-  function({event, next}) {
-    // fail on all warnings
-    if(event.level === 'warning') {
-      throw new JsonLdError(
-        'Strict mode violation occurred.',
-        'jsonld.StrictModeViolationEvent',
-        {event});
-    }
-    next();
-  },
-  // fail on unhandled events
-  // TODO: update when events are added that are acceptable in strict mode
-  api.unhandledEventHandler
-];
-
-// log warnings to console or fail
-api.basicEventHandler = [
-  api.logWarningEventHandler,
-  api.unhandledEventHandler
-];
+// fallback to throw errors for any unhandled events
+api.unhandledEventHandler = function({event}) {
+  throw new JsonLdError(
+    'No handler for event.',
+    'jsonld.UnhandledEvent',
+    {event}
+  );
+};
 
 /**
  * Set default event handler.
@@ -149,5 +155,5 @@ api.basicEventHandler = [
  *     falsey to unset.
  */
 api.setDefaultEventHandler = function({eventHandler} = {}) {
-  _defaultEventHandler = eventHandler ? _asArray(eventHandler) : [];
+  api.defaultEventHandler = eventHandler ? _asArray(eventHandler) : null;
 };

lib/jsonld.js

@@ -4,7 +4,7 @@
  * @author Dave Longley
  *
  * @license BSD 3-Clause License
- * Copyright (c) 2011-2019 Digital Bazaar, Inc.
+ * Copyright (c) 2011-2022 Digital Bazaar, Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -81,12 +81,10 @@ const {
 } = require('./nodeMap');
 
 const {
-  basicEventHandler: _basicEventHandler,
   logEventHandler: _logEventHandler,
   logWarningEventHandler: _logWarningEventHandler,
   setDefaultEventHandler: _setDefaultEventHandler,
   strictModeEventHandler: _strictModeEventHandler,
-  throwUnacceptableEventHandler: _throwUnacceptableEventHandler,
   unhandledEventHandler: _unhandledEventHandler
 } = require('./events');
 
@@ -129,6 +127,7 @@ const _resolvedContextCache = new LRU({max: RESOLVED_CONTEXT_CACHE_MAX_SIZE});
  *            unmappable values (or to throw an error when they are detected);
  *            if this function returns `undefined` then the default behavior
  *            will be used.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -268,6 +267,7 @@ jsonld.compact = async function(input, ctx, options) {
  *            unmappable values (or to throw an error when they are detected);
  *            if this function returns `undefined` then the default behavior
  *            will be used.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -422,6 +422,7 @@ jsonld.flatten = async function(input, ctx, options) {
  *          [requireAll] default @requireAll flag (default: true).
  *          [omitDefault] default @omitDefault flag (default: false).
  *          [documentLoader(url, options)] the document loader.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -521,6 +522,7 @@ jsonld.frame = async function(input, frame, options) {
  *          [base] the base IRI to use.
  *          [expandContext] a context to expand with.
  *          [documentLoader(url, options)] the document loader.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -557,6 +559,7 @@ jsonld.link = async function(input, ctx, options) {
  *            'application/n-quads' for N-Quads.
  *          [documentLoader(url, options)] the document loader.
  *          [useNative] true to use a native canonize algorithm
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -614,6 +617,7 @@ jsonld.normalize = jsonld.canonize = async function(input, options) {
  *            (boolean, integer, double), false not to (default: false).
  *          [rdfDirection] 'i18n-datatype' to support RDF transformation of
  *             @direction (default: null).
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *
  * @return a Promise that resolves to the JSON-LD document.
@@ -664,6 +668,7 @@ jsonld.fromRDF = async function(dataset, options) {
  *          [produceGeneralizedRdf] true to output generalized RDF, false
  *            to produce only standard RDF (default: false).
  *          [documentLoader(url, options)] the document loader.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -758,6 +763,7 @@ jsonld.createNodeMap = async function(input, options) {
  *            new properties where a node is in the `object` position
  *            (default: true).
  *          [documentLoader(url, options)] the document loader.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -921,6 +927,7 @@ jsonld.get = async function(url, options) {
  * @param localCtx the local context to process.
  * @param [options] the options to use:
  *          [documentLoader(url, options)] the document loader.
+ *          [safe] true to use safe mode.
  *          [eventHandler] handler for events.
  *          [contextResolver] internal use only.
  *
@@ -1008,13 +1015,10 @@ jsonld.registerRDFParser('application/nquads', NQuads.parse);
 jsonld.url = require('./url');
 
 /* Events API and handlers */
-jsonld.setDefaultEventHandler = _setDefaultEventHandler;
-jsonld.basicEventHandler = _basicEventHandler;
 jsonld.logEventHandler = _logEventHandler;
 jsonld.logWarningEventHandler = _logWarningEventHandler;
 jsonld.setDefaultEventHandler = _setDefaultEventHandler;
 jsonld.strictModeEventHandler = _strictModeEventHandler;
-jsonld.throwUnacceptableEventHandler = _throwUnacceptableEventHandler;
 jsonld.unhandledEventHandler = _unhandledEventHandler;
 
 /* Utility API */