Add event handler.

- Current use is for custom handling of warnings.
- Replay events when using cached contexts.
- Flexible chainable handlers. Can use functions, arrays, object
  code/function map shortcut, or a combination of these.
- Use handler for current context warnings.

Author: davidlehn

CHANGELOG.md

@@ -28,6 +28,9 @@
 - Support for expansion and compaction of values container `"@direction"`.
 - Support for RDF transformation of `@direction` when `rdfDirection` is
   'i18n-datatype'.
+- Event handler option "`handleEvent`" to allow custom handling of warnings and
+  potentially other events in the future. Handles event replay for cached
+  contexts.
 
 ### Removed
 - Experimental non-standard `protectedMode` option.

lib/context.js

@@ -20,6 +20,10 @@ const {
   parse: parseUrl
 } = require('./url');
 
+const {
+  handleEvent: _handleEvent
+} = require('./events');
+
 const {
   asArray: _asArray,
   compareShortestLeast: _compareShortestLeast
@@ -61,6 +65,23 @@ api.process = async ({
     return activeCtx;
   }
 
+  // event handler for capturing events to replay when using a cached context
+  const events = [];
+  const handleEvent = [
+    ({event, next}) => {
+      events.push(event);
+      next();
+    }
+  ];
+  // chain to original handler
+  if(options.handleEvent) {
+    handleEvent.push(options.handleEvent);
+  }
+  // store original options to use when replaying events
+  const originalOptions = options;
+  // shallow clone options with custom event handler
+  options = Object.assign({}, options, {handleEvent});
+
   // resolve contexts
   const resolved = await options.contextResolver.resolve({
     context: localCtx,
@@ -111,7 +132,12 @@ api.process = async ({
     // get processed context from cache if available
     const processed = resolvedContext.getProcessed(activeCtx);
     if(processed) {
-      rval = activeCtx = processed;
+      // replay events with original non-capturing options
+      for(const event of processed.events) {
+        _handleEvent({event, options: originalOptions});
+      }
+
+      rval = activeCtx = processed.context;
       continue;
     }
 
@@ -330,7 +356,10 @@ api.process = async ({
     }
 
     // cache processed result
-    resolvedContext.setProcessed(activeCtx, rval);
+    resolvedContext.setProcessed(activeCtx, {
+      context: rval,
+      events
+    });
   }
 
   return rval;
@@ -394,9 +423,18 @@ api.createTermDefinition = ({
       'jsonld.SyntaxError',
       {code: 'keyword redefinition', context: localCtx, term});
   } else if(term.match(KEYWORD_PATTERN)) {
-    // FIXME: remove logging and use a handler
-    console.warn('WARNING: terms beginning with "@" are reserved' +
-      ' for future use and ignored', {term});
+    _handleEvent({
+      event: {
+        code: 'invalid reserved term',
+        level: 'warning',
+        message:
+          'Terms beginning with "@" are reserved for future use and ignored.',
+        details: {
+          term
+        }
+      },
+      options
+    });
     return;
   } else if(term === '') {
     throw new JsonLdError(
@@ -488,9 +526,19 @@ api.createTermDefinition = ({
     }
 
     if(reverse.match(KEYWORD_PATTERN)) {
-      // FIXME: remove logging and use a handler
-      console.warn('WARNING: values beginning with "@" are reserved' +
-        ' for future use and ignored', {reverse});
+      _handleEvent({
+        event: {
+          code: 'invalid reserved value',
+          level: 'warning',
+          message:
+            'Values beginning with "@" are reserved for future use and' +
+            ' ignored.',
+          details: {
+            reverse
+          }
+        },
+        options
+      });
       if(previousMapping) {
         activeCtx.mappings.set(term, previousMapping);
       } else {
@@ -513,9 +561,19 @@ api.createTermDefinition = ({
       // reserve a null term, which may be protected
       mapping['@id'] = null;
     } else if(!api.isKeyword(id) && id.match(KEYWORD_PATTERN)) {
-      // FIXME: remove logging and use a handler
-      console.warn('WARNING: values beginning with "@" are reserved' +
-        ' for future use and ignored', {id});
+      _handleEvent({
+        event: {
+          code: 'invalid reserved value',
+          level: 'warning',
+          message:
+            'Values beginning with "@" are reserved for future use and' +
+            ' ignored.',
+          details: {
+            id
+          }
+        },
+        options
+      });
       if(previousMapping) {
         activeCtx.mappings.set(term, previousMapping);
       } else {

lib/events.js

@@ -0,0 +1,92 @@
+/*
+ * Copyright (c) 2020 Digital Bazaar, Inc. All rights reserved.
+ */
+'use strict';
+
+const JsonLdError = require('./JsonLdError');
+
+const {
+  isArray: _isArray
+} = require('./types');
+
+const {
+  asArray: _asArray
+} = require('./util');
+
+const api = {};
+module.exports = api;
+
+/**
+ * Handle an event.
+ *
+ * Top level APIs have a common 'handleEvent' option. This option can be a
+ * function, array of functions, object mapping event.code to functions (with a
+ * default to call next()), or any combination of such handlers. Handlers will
+ * be called with an object with an 'event' entry and a 'next' function. Custom
+ * 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']
+ *   {string} message - human readable message
+ *   {object} details - event specific details
+ * @param {object} options - original API options
+ */
+api.handleEvent = ({
+  event,
+  options
+}) => {
+  const handlers = [].concat(
+    options.handleEvent ? _asArray(options.handleEvent) : [],
+    _defaultHandler
+  );
+  _handle({event, handlers});
+};
+
+function _handle({event, handlers}) {
+  let doNext = true;
+  for(let i = 0; doNext && i < handlers.length; ++i) {
+    doNext = false;
+    const handler = handlers[i];
+    if(_isArray(handler)) {
+      doNext = _handle({event, handlers: handler});
+    } else if(typeof handler === 'function') {
+      handler({event, next: () => {
+        doNext = true;
+      }});
+    } else if(typeof handler === 'object') {
+      if(event.code in handler) {
+        handler[event.code]({event, next: () => {
+          doNext = true;
+        }});
+      } else {
+        doNext = true;
+      }
+    } else {
+      throw new JsonLdError(
+        'Invalid event handler.',
+        'jsonld.InvalidEventHandler',
+        {event});
+    }
+  }
+  return doNext;
+}
+
+function _defaultHandler({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});
+}

lib/jsonld.js

@@ -123,6 +123,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the compacted output.
@@ -271,6 +272,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the expanded output.
@@ -368,6 +370,7 @@ jsonld.expand = async function(input, options) {
  *          [base] the base IRI to use.
  *          [expandContext] a context to expand with.
  *          [documentLoader(url, options)] the document loader.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the flattened output.
@@ -423,6 +426,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the framed output.
@@ -505,6 +509,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the linked output.
@@ -540,6 +545,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
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the normalized output.
@@ -594,6 +600,7 @@ jsonld.normalize = jsonld.canonize = async function(input, options) {
  *            (default: false).
  *          [useNativeTypes] true to convert XSD types into native types
  *            (boolean, integer, double), false not to (default: false).
+ *          [handleEvent] handler for events such as warnings.
  *
  * @return a Promise that resolves to the JSON-LD document.
  */
@@ -643,6 +650,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the RDF dataset.
@@ -696,6 +704,7 @@ jsonld.toRDF = async function(input, options) {
  *          [expandContext] a context to expand with.
  *          [issuer] a jsonld.IdentifierIssuer to use to label blank nodes.
  *          [documentLoader(url, options)] the document loader.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the merged node map.
@@ -735,6 +744,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the merged output.
@@ -897,6 +907,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.
+ *          [handleEvent] handler for events such as warnings.
  *          [contextResolver] internal use only.
  *
  * @return a Promise that resolves to the new active context.