Improve event handling.

davidlehn · davidlehn · commit fc29ecd0add3 · 2022-08-10T11:17:26.000-04:00
- Setup eventHandler defaults once at top level.
- Use simple existence check to optimize if handlers need to be called.
- Better naming for event capture handler.
diff --git a/lib/context.js b/lib/context.js
@@ -67,20 +67,20 @@ api.process = async ({
 
   // event handler for capturing events to replay when using a cached context
   const events = [];
-  const eventHandler = [
+  const eventCaptureHandler = [
     ({event, next}) => {
       events.push(event);
       next();
     }
   ];
   // chain to original handler
   if(options.eventHandler) {
-    eventHandler.push(options.eventHandler);
+    eventCaptureHandler.push(options.eventHandler);
   }
   // store original options to use when replaying events
   const originalOptions = options;
-  // shallow clone options with custom event handler
-  options = {...options, eventHandler};
+  // shallow clone options with event capture handler
+  options = {...options, eventHandler: eventCaptureHandler};
 
   // resolve contexts
   const resolved = await options.contextResolver.resolve({
@@ -133,9 +133,11 @@ api.process = async ({
     // get processed context from cache if available
     const processed = resolvedContext.getProcessed(activeCtx);
     if(processed) {
-      // replay events with original non-capturing options
-      for(const event of processed.events) {
-        _handleEvent({event, options: originalOptions});
+      if(originalOptions.eventHandler) {
+        // replay events with original non-capturing options
+        for(const event of processed.events) {
+          _handleEvent({event, options: originalOptions});
+        }
       }
 
       rval = activeCtx = processed.context;
@@ -474,18 +476,20 @@ api.createTermDefinition = ({
       'jsonld.SyntaxError',
       {code: 'keyword redefinition', context: localCtx, term});
   } else if(term.match(KEYWORD_PATTERN)) {
-    _handleEvent({
-      event: {
-        code: 'invalid reserved term',
-        level: 'warning',
-        message:
-          'Terms beginning with "@" are reserved for future use and ignored.',
-        details: {
-          term
-        }
-      },
-      options
-    });
+    if(options.eventHandler) {
+      _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(
@@ -566,19 +570,21 @@ api.createTermDefinition = ({
     }
 
     if(reverse.match(KEYWORD_PATTERN)) {
-      _handleEvent({
-        event: {
-          code: 'invalid reserved value',
-          level: 'warning',
-          message:
-            'Values beginning with "@" are reserved for future use and' +
-            ' ignored.',
-          details: {
-            reverse
-          }
-        },
-        options
-      });
+      if(options.eventHandler) {
+        _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 {
@@ -612,19 +618,21 @@ api.createTermDefinition = ({
       // reserve a null term, which may be protected
       mapping['@id'] = null;
     } else if(!api.isKeyword(id) && id.match(KEYWORD_PATTERN)) {
-      _handleEvent({
-        event: {
-          code: 'invalid reserved value',
-          level: 'warning',
-          message:
-            'Values beginning with "@" are reserved for future use and' +
-            ' ignored.',
-          details: {
-            id
-          }
-        },
-        options
-      });
+      if(options.eventHandler) {
+        _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 {
@@ -1144,17 +1152,19 @@ function _expandIri(activeCtx, value, relativeTo, localCtx, defined, options) {
     if(expandedResult !== undefined) {
       value = expandedResult;
     } else {
-      _handleEvent({
-        event: {
-          code: 'relative IRI after expansion',
-          level: 'warning',
-          message: 'Expansion resulted in a relative IRI.',
-          details: {
-            value
-          }
-        },
-        options
-      });
+      if(options.eventHandler) {
+        _handleEvent({
+          event: {
+            code: 'relative IRI after expansion',
+            level: 'warning',
+            message: 'Expansion resulted in a relative IRI.',
+            details: {
+              value
+            }
+          },
+          options
+        });
+      }
     }
   }
 
diff --git a/lib/events.js b/lib/events.js
@@ -21,18 +21,25 @@ module.exports = api;
 api.defaultEventHandler = null;
 
 /**
- * Check if event handler is in use in options or by default.
+ * Setup event handler.
  *
- * 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.
+ * Return an array event handler constructed from an optional safe mode
+ * handler, an optional options event handler, and an optional default handler.
  *
- * @param {object} options - processing options:
- *   {boolean} [safe] - flag for Safe Mode.
+ * @param {object} options - processing options
  *   {function|object|array} [eventHandler] - an event handler.
+ *
+ * @return an array event handler.
  */
-api.hasEventHandler = options => {
-  return options.safe || options.eventHandler || api.defaultEventHandler;
+api.setupEventHandler = ({options = {}}) => {
+  // build in priority order
+  const eventHandler = [].concat(
+    options.safe ? api.safeModeEventHandler : [],
+    options.eventHandler ? _asArray(options.eventHandler) : [],
+    api.defaultEventHandler ? api.defaultEventHandler : []
+  );
+  // null if no handlers
+  return eventHandler.length === 0 ? null : eventHandler;
 };
 
 /**
@@ -45,24 +52,23 @@ api.hasEventHandler = options => {
  * handlers should process the event as appropriate. The 'next()' function
  * should be called to let the next handler process the event.
  *
+ * NOTE: Only call this function if options.eventHandler is set and is an
+ * array of hanlers. This is an optimization. Callers are expected to check
+ * for an event handler before constructing events and calling this function.
+ *
  * @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 - processing options
+ *   {array} eventHandler - an event handler array.
  */
 api.handleEvent = ({
   event,
   options
 }) => {
-  const handlers = [].concat(
-    // priority is safe mode handler, options handler, then default handler
-    options.safe ? api.safeModeEventHandler : [],
-    options.eventHandler ? _asArray(options.eventHandler) : [],
-    api.defaultEventHandler ? api.defaultEventHandler : []
-  );
-  _handle({event, handlers});
+  _handle({event, handlers: options.eventHandler});
 };
 
 function _handle({event, handlers}) {
diff --git a/lib/expand.js b/lib/expand.js
@@ -465,18 +465,20 @@ async function _expandObject({
         expandedParent
       });
       if(expandedProperty === undefined) {
-        _handleEvent({
-          event: {
-            code: 'invalid property expansion',
-            level: 'warning',
-            message: 'Invalid expansion for property.',
-            details: {
-              // FIXME: include expandedProperty before mapping
-              property: key
-            }
-          },
-          options
-        });
+        if(options.eventHandler) {
+          _handleEvent({
+            event: {
+              code: 'invalid property expansion',
+              level: 'warning',
+              message: 'Invalid expansion for property.',
+              details: {
+                // FIXME: include expandedProperty before mapping
+                property: key
+              }
+            },
+            options
+          });
+        }
         continue;
       }
     }
@@ -628,17 +630,19 @@ async function _expandObject({
       // ensure language tag matches BCP47
       for(const language of value) {
         if(_isString(language) && !language.match(REGEX_BCP47)) {
-          _handleEvent({
-            event: {
-              code: 'invalid @language value',
-              level: 'warning',
-              message: '@language value must be valid BCP47.',
-              details: {
-                language
-              }
-            },
-            options
-          });
+          if(options.eventHandler) {
+            _handleEvent({
+              event: {
+                code: 'invalid @language value',
+                level: 'warning',
+                message: '@language value must be valid BCP47.',
+                details: {
+                  language
+                }
+              },
+              options
+            });
+          }
         }
       }
 
diff --git a/lib/fromRdf.js b/lib/fromRdf.js
@@ -341,17 +341,19 @@ function _RDFToObject(o, useNativeTypes, rdfDirection, options) {
       if(language.length > 0) {
         rval['@language'] = language;
         if(!language.match(REGEX_BCP47)) {
-          _handleEvent({
-            event: {
-              code: 'invalid @language value',
-              level: 'warning',
-              message: '@language value must be valid BCP47.',
-              details: {
-                language
-              }
-            },
-            options
-          });
+          if(options.eventHandler) {
+            _handleEvent({
+              event: {
+                code: 'invalid @language value',
+                level: 'warning',
+                message: '@language value must be valid BCP47.',
+                details: {
+                  language
+                }
+              },
+              options
+            });
+          }
         }
       }
       rval['@direction'] = direction;
diff --git a/lib/jsonld.js b/lib/jsonld.js
@@ -84,6 +84,7 @@ const {
   logEventHandler: _logEventHandler,
   logWarningEventHandler: _logWarningEventHandler,
   setDefaultEventHandler: _setDefaultEventHandler,
+  setupEventHandler: _setupEventHandler,
   strictModeEventHandler: _strictModeEventHandler,
   unhandledEventHandler: _unhandledEventHandler
 } = require('./events');
@@ -1042,7 +1043,13 @@ function _setDefaults(options, {
   documentLoader = jsonld.documentLoader,
   ...defaults
 }) {
-  return Object.assign({}, {documentLoader}, defaults, options);
+  return Object.assign(
+    {},
+    {documentLoader},
+    defaults,
+    options,
+    {eventHandler: _setupEventHandler({options})}
+  );
 }
 
 // end of jsonld API `wrapper` factory
