Add expansionMap and compactionMap options.

Author: dlongley

CHANGELOG.md

@@ -1,5 +1,14 @@
 # jsonld ChangeLog
 
+### Added
+- Add `expansionMap` and `compactionMap` options. These
+  functions may be provided that will be called when an
+  unmapped value or property will be dropped during expansion
+  or compaction, respectively. The function map return either
+  `undefined` to cause the default behavior, some other
+  value to use instead of the default expanded/compacted value,
+  or it may throw an error to stop expansion/compaction.
+
 ## 0.5.9 - 2017-09-21
 
 ### Fixed

lib/jsonld.js

@@ -105,6 +105,14 @@ var wrapper = function(jsonld) {
  *          [skipExpansion] true to assume the input is expanded and skip
  *            expansion, false not to, defaults to false.
  *          [documentLoader(url, callback(err, remoteDoc))] the document loader.
+ *          [expansionMap(info)] a function that can be used to custom map
+ *            unmappable values (or to throw an error when they are detected);
+ *            if this function returns `undefined` then the default behavior
+ *            will be used.
+ *          [compactionMap(info)] a function that can be used to custom map
+ *            unmappable values (or to throw an error when they are detected);
+ *            if this function returns `undefined` then the default behavior
+ *            will be used.
  * @param callback(err, compacted, ctx) called once the operation completes.
  */
 jsonld.compact = function(input, ctx, options, callback) {
@@ -184,7 +192,11 @@ jsonld.compact = function(input, ctx, options, callback) {
       var compacted;
       try {
         // do compaction
-        compacted = new Processor().compact(activeCtx, null, expanded, options);
+        const processor = new Processor();
+        if(typeof options.compactionMap === 'function') {
+          processor.compactionMap = options.compactionMap;
+        }
+        compacted = processor.compact(activeCtx, null, expanded, options);
       } catch(ex) {
         return callback(ex);
       }
@@ -270,6 +282,10 @@ jsonld.compact = function(input, ctx, options, callback) {
  *          [keepFreeFloatingNodes] true to keep free-floating nodes,
  *            false not to, defaults to false.
  *          [documentLoader(url, callback(err, remoteDoc))] the document loader.
+ *          [expansionMap(info)] a function that can be used to custom map
+ *            unmappable values (or to throw an error when they are detected);
+ *            if this function returns `undefined` then the default behavior
+ *            will be used.
  * @param [callback(err, expanded)] called once the operation completes.
  *
  * @return a Promise that resolves to the expanded output.
@@ -357,6 +373,10 @@ jsonld.expand = util.callbackify(async (input, options) => {
       let expanded;
       try {
         const processor = new Processor();
+        if(typeof options.expansionMap === 'function') {
+          processor.expansionMap = options.expansionMap;
+        }
+
         let activeCtx = _getInitialContext(options);
         const doc = remoteUrlContainer.document;
         const remoteContext = remoteUrlContainer.remoteContext['@context'];
@@ -949,6 +969,8 @@ jsonld.toRDF = util.callbackify(async function(input, options) {
     options.documentLoader = jsonld.loadDocument;
   }
 
+  // TODO: support toRDF custom map?
+
   // TODO: use `await` once jsonld.expand is updated
   // expand input
   //const expanded = await jsonld.expand(input)
@@ -1564,7 +1586,11 @@ const JsonLdError = require('./JsonLdError');
 /**
  * Constructs a new JSON-LD Processor.
  */
-var Processor = function() {};
+var Processor = function() {
+  // drop unmapped values by default
+  this.expansionMap = () => undefined;
+  this.compactionMap = () => undefined;
+};
 
 /**
  * Recursively compacts an element using the given active context. All values
@@ -1584,12 +1610,24 @@ Processor.prototype.compact = function(
   if(_isArray(element)) {
     var rval = [];
     for(var i = 0; i < element.length; ++i) {
-      // compact, dropping any null values
+      // compact, dropping any null values unless custom mapped
       var compacted = this.compact(
         activeCtx, activeProperty, element[i], options);
-      if(compacted !== null) {
-        rval.push(compacted);
+      if(compacted === null) {
+        // TODO: use `await` to support async
+        compacted = this.compactionMap({
+          unmappedValue: element[i],
+          activeCtx,
+          activeProperty,
+          parent: element,
+          index: i,
+          options
+        });
+        if(compacted === undefined) {
+          continue;
+        }
       }
+      rval.push(compacted);
     }
     if(options.compactArrays && rval.length === 1) {
       // use single element if no container is specified
@@ -1728,6 +1766,11 @@ Processor.prototype.compact = function(
       }
 
       // Note: expanded value must be an array due to expansion algorithm.
+      if(!_isArray(expandedValue)) {
+        throw new JsonLdError(
+          'JSON-LD expansion error; expanded value must be an array.',
+          'jsonld.SyntaxError');
+      }
 
       // preserve empty arrays
       if(expandedValue.length === 0) {
@@ -1874,10 +1917,21 @@ Processor.prototype.expand = function(
   }
 
   if(!_isArray(element) && !_isObject(element)) {
-    // drop free-floating scalars that are not in lists
+    // drop free-floating scalars that are not in lists unless custom mapped
     if(!insideList && (activeProperty === null ||
       _expandIri(activeCtx, activeProperty, {vocab: true}) === '@graph')) {
-      return null;
+      // TODO: use `await` to support async
+      const mapped = self.expansionMap({
+        unmappedValue: element,
+        activeCtx,
+        activeProperty,
+        options,
+        insideList
+      });
+      if(mapped === undefined) {
+        return null;
+      }
+      return mapped;
     }
 
     // expand element according to value expansion rules
@@ -1899,14 +1953,29 @@ Processor.prototype.expand = function(
           'Invalid JSON-LD syntax; lists of lists are not permitted.',
           'jsonld.SyntaxError', {code: 'list of lists'});
       }
-      // drop null values
-      if(e !== null) {
-        if(_isArray(e)) {
-          rval = rval.concat(e);
-        } else {
-          rval.push(e);
+
+      if(e === null) {
+        // TODO: add `await` for async support
+        e = self.expansionMap({
+          unmappedValue: element[i],
+          activeCtx,
+          activeProperty,
+          parent: element,
+          index: i,
+          options,
+          expandedParent: rval,
+          insideList
+        });
+        if(e === undefined) {
+          continue;
         }
       }
+
+      if(_isArray(e)) {
+        rval = rval.concat(e);
+      } else {
+        rval.push(e);
+      }
     }
     return rval;
   }
@@ -1937,10 +2006,23 @@ Processor.prototype.expand = function(
     // expand property
     var expandedProperty = _expandIri(activeCtx, key, {vocab: true});
 
-    // drop non-absolute IRI keys that aren't keywords
+    // drop non-absolute IRI keys that aren't keywords unless custom mapped
     if(expandedProperty === null ||
       !(_isAbsoluteIri(expandedProperty) || _isKeyword(expandedProperty))) {
-      continue;
+      // TODO: use `await` to support async
+      expandedProperty = self.expansionMap({
+        unmappedProperty: key,
+        activeCtx,
+        activeProperty,
+        parent: element,
+        options,
+        insideList,
+        value,
+        expandedParent: rval
+      });
+      if(expandedProperty === undefined) {
+        continue;
+      }
     }
 
     if(_isKeyword(expandedProperty)) {
@@ -2120,7 +2202,21 @@ Processor.prototype.expand = function(
 
     // drop null values if property is not @value
     if(expandedValue === null && expandedProperty !== '@value') {
-      continue;
+      // TODO: use `await` to support async
+      expandedValue = self.expansionMap({
+        unmappedValue: value,
+        expandedProperty,
+        activeCtx,
+        activeProperty,
+        parent: element,
+        options,
+        insideList,
+        key: key,
+        expandedParent: rval
+      });
+      if(expandedValue === undefined) {
+        continue;
+      }
     }
 
     // convert expanded value to @list if container specifies it
@@ -2198,9 +2294,22 @@ Processor.prototype.expand = function(
         'which can be "@type" or "@language".',
         'jsonld.SyntaxError', {code: 'invalid value object', element: rval});
     }
-    // drop null @values
+    // drop null @values unless custom mapped
     if(rval['@value'] === null) {
-      rval = null;
+      // TODO: use `await` to support async
+      const mapped = self.expansionMap({
+        unmappedValue: rval,
+        activeCtx,
+        activeProperty,
+        element,
+        options,
+        insideList
+      });
+      if(mapped !== undefined) {
+        rval = mapped;
+      } else {
+        rval = null;
+      }
     } else if('@language' in rval && !_isString(rval['@value'])) {
       // if @language is present, @value must be a string
       throw new JsonLdError(
@@ -2233,18 +2342,45 @@ Processor.prototype.expand = function(
       count = keys.length;
     }
   } else if(count === 1 && '@language' in rval) {
-    // drop objects with only @language
-    rval = null;
+    // drop objects with only @language unless custom mapped
+    // TODO: use `await` to support async
+    const mapped = self.expansionMap(rval, {
+      unmappedValue: rval,
+      activeCtx,
+      activeProperty,
+      element,
+      options,
+      insideList
+    });
+    if(mapped !== undefined) {
+      rval = mapped;
+    } else {
+      rval = null;
+    }
   }
 
-  // drop certain top-level objects that do not occur in lists
+  // drop certain top-level objects that do not occur in lists, unless custom
+  // mapped
   if(_isObject(rval) &&
     !options.keepFreeFloatingNodes && !insideList &&
     (activeProperty === null || expandedActiveProperty === '@graph')) {
     // drop empty object, top-level @value/@list, or object with only @id
     if(count === 0 || '@value' in rval || '@list' in rval ||
       (count === 1 && '@id' in rval)) {
-      rval = null;
+      // TODO: use `await` to support async
+      const mapped = self.expansionMap({
+        unmappedValue: rval,
+        activeCtx,
+        activeProperty,
+        element,
+        options,
+        insideList
+      });
+      if(mapped !== undefined) {
+        rval = mapped;
+      } else {
+        rval = null;
+      }
     }
   }