feat: add prependIri expansionMap hook and tests

Author: tplooker

lib/context.js

@@ -1043,18 +1043,96 @@ function _expandIri(activeCtx, value, relativeTo, localCtx, defined, options) {
 
   if(relativeTo.vocab && '@vocab' in activeCtx) {
     // prepend vocab
-    value = activeCtx['@vocab'] + value;
+    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
+        },
+        activeCtx,
+        options
+      });
+
+    }
+    if(expansionMapResult !== undefined) {
+      value = expansionMapResult;
+    } else {
+      // the null case preserves value as potentially relative
+      value = prependedResult;
+    }
   } else if(relativeTo.base && '@base' in activeCtx) {
     // prepend base
     if(activeCtx['@base']) {
-      // The null case preserves value as potentially relative
-      value = prependBase(prependBase(options.base, activeCtx['@base']), value);
+      const prependedResult = prependBase(
+        prependBase(options.base, activeCtx['@base']), value);
+
+      let expansionMapResult = undefined;
+      if(options && options.expansionMap) {
+        // if we are about to expand the value by prepending
+        // @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: activeCtx['@base'],
+            value,
+            result: prependedResult
+          },
+          activeCtx,
+          options
+        });
+      }
+      if(expansionMapResult !== undefined) {
+        value = expansionMapResult;
+      } else {
+        // the null case preserves value as potentially relative
+        value = prependedResult;
+      }
     }
   } else if(relativeTo.base) {
-    value = prependBase(options.base, value);
+    const prependedResult = prependBase(options.base, value);
+    let expansionMapResult = undefined;
+    if(options && options.expansionMap) {
+      // if we are about to expand the value by prepending
+      // @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: options.base,
+          value,
+          result: prependedResult
+        },
+        activeCtx,
+        options
+      });
+    }
+    if(expansionMapResult !== undefined) {
+      value = expansionMapResult;
+    } else {
+      value = prependedResult;
+    }
   }
 
-  if(!_isAbsoluteIri(value) && options.expansionMap) {
+  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,

lib/expand.js

@@ -77,7 +77,7 @@ api.expand = async ({
 }) => {
 
   // add expansion map to the processing options
-  options = { ...options, expansionMap };
+  options = {...options, expansionMap};
 
   // nothing to expand
   if(element === null || element === undefined) {