Remove compactionMap and expansionMap.

- **BREAKING**: Remove `compactionMap` and `expansionMap`. Their known
  use cases are addressed with "safe mode" and future planned features.
- Update docs.
- Update tests.
- Add partial event log tester to simplify checking only some fields.
- Add `prepending` events for `@base` and `@vocab`. Likely to be removed
  since other events better expose what the real data issues are. May
  return for a debug mode.
- Fix some tests.

Author: davidlehn

CHANGELOG.md

@@ -40,6 +40,8 @@
 - Experimental non-standard `protectedMode` option.
 - **BREAKING**: Various console warnings were removed. The newly added "safe
   mode" can stop processing where these warnings were.
+- **BREAKING**: Remove `compactionMap` and `expansionMap`. Their known use
+  cases are addressed with "safe mode" and future planned features.
 
 ## 5.2.0 - 2021-04-07
 

lib/compact.js

@@ -51,41 +51,28 @@ module.exports = api;
  *          to compact, null for none.
  * @param element the element to compact.
  * @param options the compaction options.
- * @param compactionMap the compaction map to use.
  *
  * @return a promise that resolves to the compacted value.
  */
 api.compact = async ({
   activeCtx,
   activeProperty = null,
   element,
-  options = {},
-  compactionMap = () => undefined
+  options = {}
 }) => {
   // recursively compact array
   if(_isArray(element)) {
     let rval = [];
     for(let i = 0; i < element.length; ++i) {
-      // compact, dropping any null values unless custom mapped
-      let compacted = await api.compact({
+      const compacted = await api.compact({
         activeCtx,
         activeProperty,
         element: element[i],
-        options,
-        compactionMap
+        options
       });
       if(compacted === null) {
-        compacted = await compactionMap({
-          unmappedValue: element[i],
-          activeCtx,
-          activeProperty,
-          parent: element,
-          index: i,
-          options
-        });
-        if(compacted === undefined) {
-          continue;
-        }
+        // FIXME: need event?
+        continue;
       }
       rval.push(compacted);
     }
@@ -149,8 +136,7 @@ api.compact = async ({
           activeCtx,
           activeProperty,
           element: element['@list'],
-          options,
-          compactionMap
+          options
         });
       }
     }
@@ -278,8 +264,7 @@ api.compact = async ({
           activeCtx,
           activeProperty: '@reverse',
           element: expandedValue,
-          options,
-          compactionMap
+          options
         });
 
         // handle double-reversed properties
@@ -316,8 +301,7 @@ api.compact = async ({
           activeCtx,
           activeProperty,
           element: expandedValue,
-          options,
-          compactionMap
+          options
         });
 
         if(!(_isArray(compactedValue) && compactedValue.length === 0)) {
@@ -434,8 +418,7 @@ api.compact = async ({
           activeCtx,
           activeProperty: itemActiveProperty,
           element: (isList || isGraph) ? inner : expandedItem,
-          options,
-          compactionMap
+          options
         });
 
         // handle @list
@@ -630,8 +613,7 @@ api.compact = async ({
                 activeCtx,
                 activeProperty: itemActiveProperty,
                 element: {'@id': expandedItem['@id']},
-                options,
-                compactionMap
+                options
               });
             }
           }

lib/context.js

@@ -1106,35 +1106,29 @@ function _expandIri(activeCtx, value, relativeTo, localCtx, defined, options) {
   if(relativeTo.vocab && '@vocab' in activeCtx) {
     // prepend vocab
     const prependedResult = activeCtx['@vocab'] + value;
-    let expansionMapResult = undefined;
-    if(options && options.expansionMap) {
-      // if we are about to expand the value by prepending
-      // @vocab then call the expansion map to inform
-      // interested callers that this is occurring
-
-      // TODO: use `await` to support async
-      expansionMapResult = options.expansionMap({
-        prependedIri: {
-          type: '@vocab',
-          vocab: activeCtx['@vocab'],
-          value,
-          result: prependedResult,
-          typeExpansion,
+    if(options && options.eventHandler) {
+      _handleEvent({
+        event: {
+          type: ['JsonLdEvent'],
+          code: 'prepending @vocab during expansion',
+          level: 'info',
+          message: 'Prepending @vocab during expansion.',
+          details: {
+            type: '@vocab',
+            vocab: activeCtx['@vocab'],
+            value,
+            result: prependedResult,
+            typeExpansion
+          }
         },
-        activeCtx,
         options
       });
     }
-    if(expansionMapResult !== undefined) {
-      value = expansionMapResult;
-    } else {
-      // the null case preserves value as potentially relative
-      value = prependedResult;
-    }
+    // the null case preserves value as potentially relative
+    value = prependedResult;
   } else if(relativeTo.base) {
     // prepend base
     let prependedResult;
-    let expansionMapResult;
     let base;
     if('@base' in activeCtx) {
       if(activeCtx['@base']) {
@@ -1148,50 +1142,50 @@ function _expandIri(activeCtx, value, relativeTo, localCtx, defined, options) {
       base = options.base;
       prependedResult = prependBase(options.base, value);
     }
-    if(options && options.expansionMap) {
-      // if we are about to expand the value by pre-pending
-      // @base then call the expansion map to inform
-      // interested callers that this is occurring
-
-      // TODO: use `await` to support async
-      expansionMapResult = options.expansionMap({
-        prependedIri: {
-          type: '@base',
-          base,
-          value,
-          result: prependedResult,
-          typeExpansion,
+    if(options && options.eventHandler) {
+      _handleEvent({
+        event: {
+          type: ['JsonLdEvent'],
+          code: 'prepending @base during expansion',
+          level: 'info',
+          message: 'Prepending @base during expansion.',
+          details: {
+            type: '@base',
+            base,
+            value,
+            result: prependedResult,
+            typeExpansion
+          }
         },
-        activeCtx,
         options
       });
     }
-    if(expansionMapResult !== undefined) {
-      value = expansionMapResult;
-    } else {
-      // the null case preserves value as potentially relative
-      value = prependedResult;
-    }
+    // the null case preserves value as potentially relative
+    value = prependedResult;
   }
 
-  if(!_isAbsoluteIri(value) && options && options.expansionMap) {
-    // if the result of the expansion is not an absolute iri then
-    // call the expansion map to inform interested callers that
-    // the resulting value is a relative iri, which can result in
-    // it being dropped when converting to other RDF representations
-
-    // TODO: use `await` to support async
-    const expandedResult = options.expansionMap({
-      relativeIri: value,
-      activeCtx,
-      typeExpansion,
+  // FIXME: duplicate? needed? maybe just enable in a verbose debug mode
+  /*
+  if(!_isAbsoluteIri(value) && options && options.eventHandler) {
+    // emit event indicating a relative IRI was found, which can result in it
+    // being dropped when converting to other RDF representations
+    _handleEvent({
+      event: {
+        type: ['JsonLdEvent'],
+        code: 'relative IRI after expansion',
+        // FIXME: what level?
+        level: 'warning',
+        message: 'Relative IRI after expansion.',
+        details: {
+          relativeIri: value,
+          typeExpansion
+        }
+      },
       options
     });
-    if(expandedResult !== undefined) {
-      value = expandedResult;
-    }
     // NOTE: relative reference events emitted at calling sites as needed
   }
+  */
 
   return value;
 }