Event handler improvements.

- Add basic event handlers (can be used to construct more complex
  handlers)
  - log all events and continue
  - fail on unhandled events
  - fail on unacceptable events
  - log warnings and continue
  - strict mode to fail on all current warnings
- Add default event handler feature.

Author: davidlehn

lib/events.js

@@ -16,6 +16,8 @@ const {
 const api = {};
 module.exports = api;
 
+let _defaultEventHandler = [];
+
 /**
  * Handle an event.
  *
@@ -42,7 +44,7 @@ api.handleEvent = ({
 }) => {
   const handlers = [].concat(
     options.eventHandler ? _asArray(options.eventHandler) : [],
-    _defaultHandler
+    ..._defaultEventHandler
   );
   _handle({event, handlers});
 };
@@ -76,17 +78,76 @@ function _handle({event, handlers}) {
   return doNext;
 }
 
-function _defaultHandler({event}) {
+// logs all events and continues
+api.logEventHandler = function({event, next}) {
+  console.warn(`EVENT: ${event.message}`, {
+    code: event.code,
+    level: event.level,
+    details: event.details
+  });
+  next();
+};
+
+// fallback to throw errors for any unhandled events
+api.unhandledEventHandler = function({event}) {
+  throw new JsonLdError(
+    'No handler for event.',
+    'jsonld.UnhandledEvent',
+    {event});
+};
+
+// throw with event details
+api.throwUnacceptableEventHandler = function({event}) {
+  throw new JsonLdError(
+    event.message,
+    'jsonld.UnacceptableEvent',
+    {event});
+};
+
+// log 'warning' level events
+api.logWarningEventHandler = function({event}) {
   if(event.level === 'warning') {
     console.warn(`WARNING: ${event.message}`, {
       code: event.code,
       details: event.details
     });
-    return;
   }
-  // fallback to ensure events are handled somehow
-  throw new JsonLdError(
-    'No handler for event.',
-    'jsonld.UnhandledEvent',
-    {event});
-}
+};
+
+// strict handler that rejects warning conditions
+api.strictModeEventHandler = [
+  function({event, next}) {
+    // fail on all warnings
+    if(event.level === 'warning') {
+      throw new JsonLdError(
+        event.message,
+        '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
+];
+
+/**
+ * Set default event handler.
+ *
+ * By default, all event are unhandled. It is recommended to pass in an
+ * eventHandler into each call. However, this call allows using a default
+ * eventHandler when one is not otherwise provided.
+ *
+ * @param {object} options - default handler options:
+ *   {function|object|array} eventHandler - a default event handler.
+ *     falsey to unset.
+ */
+api.setDefaultEventHandler = function({eventHandler} = {}) {
+  _defaultEventHandler = eventHandler ? _asArray(eventHandler) : [];
+};

lib/jsonld.js

@@ -80,6 +80,16 @@ const {
   mergeNodeMaps: _mergeNodeMaps
 } = require('./nodeMap');
 
+const {
+  basicEventHandler: _basicEventHandler,
+  logEventHandler: _logEventHandler,
+  logWarningEventHandler: _logWarningEventHandler,
+  setDefaultEventHandler: _setDefaultEventHandler,
+  strictModeEventHandler: _strictModeEventHandler,
+  throwUnacceptableEventHandler: _throwUnacceptableEventHandler,
+  unhandledEventHandler: _unhandledEventHandler
+} = require('./events');
+
 /* eslint-disable indent */
 // attaches jsonld API to the given object
 const wrapper = function(jsonld) {
@@ -997,6 +1007,16 @@ jsonld.registerRDFParser('application/nquads', NQuads.parse);
 /* URL API */
 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 */
 jsonld.util = util;
 // backwards compatibility

tests/misc.js

@@ -493,8 +493,37 @@ function addEventCounts(counts, event) {
 }
 
 describe.only('events', () => {
-  // FIXME add default handler tests
-  // FIXME add object '*' handler tests
+  // FIXME/TODO add object '*' handler and tests?
+
+  it('check default handler called', async () => {
+    const d =
+{
+  "relative": "test"
+}
+;
+    const ex = [];
+
+    const counts = {};
+    const eventHandler = ({event}) => {
+      addEventCounts(counts, event);
+    };
+
+    jsonld.setDefaultEventHandler({eventHandler});
+
+    const e = await jsonld.expand(d);
+
+    assert.deepStrictEqual(e, ex);
+    assert.deepStrictEqual(counts, {
+      codes: {
+        'invalid property expansion': 1,
+        'relative IRI after expansion': 2
+      },
+      events: 3
+    });
+
+    // reset default
+    jsonld.setDefaultEventHandler();
+  });
 
   it('handle warning event with function', async () => {
     const d =