json-utilities

vlerdas-json-utilities

A collection of utilities and tools related to JSON: json2jsonPush, resolvePaths, and utils. Named json-utilities in NPM.

Install

1. npm install json-utilities --save

*Note the "--save" parameter automatically adds the dependency to your  
 package.json file, it is an optional parameter.

API

##Logger This package requires that the calling module export a logger to modules.export.logger. The one that works out of the box is the vcommons logger. However, any logger can be used as long as the level functions are mapped to the levels in vcommons.

var config = require('config');
var logger = require('vcommons').log.getLogger('vlerdas-http-enricher', config.log);
module.exports.logger = logger;

The 'config' library is not strictly required for vcommons, but vcommons does expect the configuration to be passed to it, as can be seen in default.json or this object (See the vcommons project for more information):

{
    "console":{
       "level":"trace",
       "colorize":true,
       "label":"vlerdas-http-enricher",
       "timestamp":true
       },
    "file":{
       "filename":"vlerdas-http-enricher.log",
       "level":"trace"
       }
}

json2jsonPush module

A module that pushes properties within a source JSON Object to a separate destination JSON Object. The module uses a configuration file that defines what properties should be "pushed" from the source JSON Object to the destination JSON Object. The module can insert JSON properties at a specific location if the target JSON location\path is missing in the target JSON, and if given a sequence order of the children of the parent property. The configuration file is meant to make the json2jsonPush module reusable against any two JSON Objects.

1. Configure a push configuration JSON file following the format at /examples/pushConfigExample_1 or _2.json. An empty template of a push configuration can be found at /examples/emptyPushConfigSample.json

2. See /examples/json2jsonPushExample_1.js and json2jsonPushExample_2.js for examples of how to use json2jsonPush in your project.

###functions

####initiate (sourceJSON, targetJSON, pushConfigration) Moves json properties from source JSON to target JSON via configuration file.

examples/json2jsonPush/json2jsonPushExample_2.js

var fs = require('fs');
var json2jsonPush = require('json-utilities').json2jsonPush; 

var nconf = require('nconf');
nconf.file({
    file : 'pushConfigExample_2.json'
});
var pushConfig = nconf.get('pushConfig');

var sourceJSON = fs.readFileSync('./sourceJSON.json');
var targetJSON = fs.readFileSync('./targetJSON.json');

try {
    var json = json2jsonPush.initiate(sourceJSON, targetJSON, pushConfig);
    console.log(JSON.stringify(json));
} catch (err) {
    console.log(err);
    throw err;
}

examples/json2jsonPush/sourceJSON.json

[  {
	"nc:DocumentCreationDate" : {
		"nc:Date" : "2013-11-28",
		"nc:Time" : "T14:59:35-05:00"
	},
	"nc:DocumentDescriptionText" : "Ankle Conditions",
	"nc:DocumentIdentification" : {
		"nc:IdentificationID" : "314e8cc3-1096-48bb-bf77-36ce6a83d0ec"
	},
	"nc:DocumentStatus" : {
		"nc:StatusText" : "Completed"
	},
	"nc:DocumentTitleText" : "Ankle Conditions",
	"nc:DocumentFileControlID" : "5298f229e11f069427000001",
	"nc:DocumentFormatText" : ["application/xml", "application/text"]
		
} ]

examples/json2jsonPush/targetJSON.json

[  {
		"nc:DocumentDescriptionText" : "Ankle Conditions",
		"nc:DocumentIdentification" : {
			"nc:IdentificationID" : "314e8cc3-1096-48bb-bf77-36ce6a83d0ec"
		},
		"nc:DocumentTitleText" : "Ankle Conditions"
} ]

Results of initiate function of json2jsonPush

[ {
	"nc:DocumentDescriptionText" : "Ankle Conditions",
	"nc:DocumentFileControlID" : "5298f229e11f069427000001",
	"nc:DocumentFormatText" : [ "application/xml", "application/text" ],
	"nc:DocumentIdentification" : {
		"nc:IdentificationID" : "314e8cc3-1096-48bb-bf77-36ce6a83d0ec"
	},
	"nc:DocumentStatus" : {
		"nc:StatusText" : "Completed"
	},
	"nc:DocumentTitleText" : "Ankle Conditions",
	"nc:Date" : "2013-11-28"
} ]

examples/json2jsonPush/pushConfigExample_2.json - The Push Configuration

{
	"pushConfig": {
		"pushes": [
			{
				"fromParent": "nc:DocumentCreationDate",
			 	"fromTarget": "nc:Date",
			 	"fromTargetChildLimiter": "",
			 	"fromTargetValueEquals": "",
			 	"fromTargetValueContains": "",
			 	"fromTargetRequired": true,
			 	
			 	"toParent": "/",
			 	"toTarget" : "nc:Date",
			 	"toTargetChildLimiter": "",
			 	"toTargetValueEquals": "",
			 	"toTargetValueContains": "",
			 	"toTargetRequired": false,
			 	"toTargetExist" : null,
			 	"toParentId" : 1
			 },
			 {
				"fromParent": "/",
			 	"fromTarget": "nc:DocumentStatus",
			 	"fromTargetChildLimiter": "",
			 	"fromTargetValueEquals": "",
			 	"fromTargetValueContains": "",
			 	"fromTargetRequired": true,
			 	
			 	"toParent": "/",
			 	"toTarget" : "nc:DocumentStatus",
			 	"toTargetChildLimiter": "",
			 	"toTargetValueEquals": "",
			 	"toTargetValueContains": "",
			 	"toTargetRequired": false,
			 	"toTargetExist" : null,
			 	"toParentId" : 1
			 },
			 {
				"fromParent": "/",
			 	"fromTarget": "nc:DocumentFileControlID",
			 	"fromTargetChildLimiter": "",
			 	"fromTargetValueEquals": "",
			 	"fromTargetValueContains": "",
			 	"fromTargetRequired": false,
			 	
			 	"toParent": "/",
			 	"toTarget" : "nc:DocumentFileControlID",
			 	"toTargetChildLimiter": "",
			 	"toTargetValueEquals": "",
			 	"toTargetValueContains": "",
			 	"toTargetRequired": false,
			 	"toTargetExist" : null,
			 	"toParentId" : 1
			 },
			 {
				"fromParent": "/",
			 	"fromTarget": "nc:DocumentFormatText",
			 	"fromTargetChildLimiter": "nc:DocumentFormatText",
			 	"fromTargetValueEquals": "",
			 	"fromTargetValueContains": "xml",
			 	"fromTargetRequired": true,
			 	
			 	"toParent": "/",
			 	"toTarget" : "nc:DocumentFormatText",
			 	"toTargetChildLimiter": "",
			 	"toTargetValueEquals": "",
			 	"toTargetValueContains": "",
			 	"toTargetRequired": false,
			 	"toTargetExist" : null,
			 	"toParentId" : 1
			 },
			 {
				"fromParent": "/",
			 	"fromTarget": "nc:DocumentFormatText",
			 	"fromTargetChildLimiter": "nc:DocumentFormatText",
			 	"fromTargetValueEquals": "application/text",
			 	"fromTargetValueContains": "",
			 	"fromTargetRequired": false,
			 	
			 	"toParent": "/",
			 	"toTarget" : "nc:DocumentFormatText",
			 	"toTargetChildLimiter": "",
			 	"toTargetValueEquals": "",
			 	"toTargetValueContains": "",
			 	"toTargetRequired": false,
			 	"toTargetExist" : null,
			 	"toParentId" : 1
			 }
		],
		"toParents": [
	    	{
	    		"id": 1,
	    		"name": "nc:Document",
	    		"childrenSequence": [	
	    		    "nc:CaveatText",
	    			"nc:DocumentAlternativeTitleText",
	    			"nc:DocumentApplicationName",
	    			"nc:DocumentApprovedIndicator",
	    			"nc:DocumentBinary",
	    			"nc:DocumentCategoryDescriptionText",
	    			"nc:DocumentCategoryID",
	    			"nc:DocumentCategoryName",
	    			"nc:DocumentCategoryText",
	    			"nc:DocumentCopyrightIndicator",
	    			"nc:DocumentCountryCode",
	    			"nc:DocumentCreationDate",
	    			"nc:DocumentDescriptionText",
	    			"nc:DocumentDispositionAuthorityName",
	    			"nc:DocumentDispositionInstructionText",
	    			"nc:DocumentDisputedIndicator",
	    			"nc:DocumentDisputedReasonText",
	    			"nc:DocumentEffectiveDate",
	    			"nc:DocumentEntrySubmitter",
	    			"nc:DocumentExpirationDate",
	    			"nc:DocumentFileControlID",
	    			"nc:DocumentFiledDate",
	    			"nc:DocumentFileExtensionText",
	    			"nc:DocumentFileName",
	    			"nc:DocumentFormatText",
	    			"nc:DocumentGroupID",
	    			"nc:DocumentIdentification",
	    			"nc:DocumentInformationCutOffDate",
	    			"nc:DocumentIntelligenceCategoryCode",
	    			"nc:DocumentKeywordText",
	    			"nc:DocumentLastModifiedDate",
	    			"nc:DocumentLocation",
	    			"nc:DocumentLocationURI",
	    			"nc:DocumentManagementCyclePeriodText",
	    			"nc:DocumentMediaCategoryText",
	    			"nc:DocumentMediumText",
	    			"nc:DocumentOtherAddresseeName",
	    			"nc:DocumentPermanentRecordIndicator",
	    			"nc:DocumentPostDate",
	    			"nc:DocumentPrivacyActIndicator",
	    			"nc:DocumentPublicationDate",
	    			"nc:DocumentReceivedDate",
	    			"nc:DocumentRecipient",
	    			"nc:DocumentRelatedResourceText",
	    			"nc:DocumentRelationText",
	    			"nc:DocumentRightsText",
	    			"nc:DocumentSequenceID",
	    			"nc:DocumentSource",
	    			"nc:DocumentSourceText",
	    			"nc:DocumentStatus",
	    			"nc:DocumentSubjectCode",
	    			"nc:DocumentSubjectText",
	    			"nc:DocumentSummaryText",
	    			"nc:DocumentSupplementalMarkingText",
	    			"nc:DocumentTitleText",
	    			"nc:DocumentVitalIndicator",
	    			"nc:SecurityLevelText",
	    			"nc:DocumentAuthor",
	    			"nc:DocumentContributor",
	    			"nc:DocumentCoverage",
	    			"nc:DocumentCreator",
	    			"nc:DocumentFormatCategoryText",
	    			"nc:DocumentLanguage",
	    			"nc:DocumentSubmissionFee",
	    			"nc:DocumentSubmitter"
	    		]
	    	}
		 ]
	}
}

####validateJson2JsonPushConfiguration (pushConfigration) Validates a push configuration separately from the initiate fucntion. The initiate function will automatically run this validation

examples/json2jsonPush/json2jsonPushValidationExample.js

try {
	var boolPushConfig = json2jsonPush.validateJson2JsonPushConfiguration(pushConfig);
} catch (err) {
	console.log(err);
	throw err;
}

####validateExistenceOfRequiredTargets (json, pushConfigration, side) Validates the existence of required target properties within the push congfiguration separately from the initiate fucntion. The initiate function will automatically run this validation.

examples/json2jsonPush/json2jsonPushValidationExample.js

var CONSTANTS = {
		pushSides: {
			from: "from",
			to: "to"
		}
	};

try {
	var boolReqFrom = json2jsonPush.validateExistenceOfRequiredTargets(pushSourceJSON, pushConfig, CONSTANTS.pushSides.from);
	var boolReqTo = json2jsonPush.validateExistenceOfRequiredTargets(pushTargetJSON, pushConfig, CONSTANTS.pushSides.to);
} catch (err) {
	console.log(err);
	throw err;
}

Push & ToParent objects contructors

While push configuration is better off coming from a push configuration json file, it can also be instantiated with the following json2jsonPush object constructors.

var toParent = new json2jsonPush.ToParent(id, name, childrenSequence);

var push = new json2jsonPush.Push(fromParent, fromTarget, fromTargetChildLimiter, fromTargetValueEquals,
fromTargetValueContains,fromTargetRequired, toParent, toTarget, toTargetChildLimiter, toTargetValueEquals,
toTargetValueContains, toTargetRequired, toTargetExist, toParentId);

resolvePaths module

This module in the json-utilities package allows the user to navigate through JSON in a JavaSscript object and execute a number of interrelated JSON Paths (Similar to XPaths in XML), use the results of one JSON Path to as an index into the results of a different JSON path, use previously resolved values as variables in new JSON Paths, to arrive at a return value. The JSON paths, relationships between the JSON paths, and the return value are configurable. For example, one JSON Path may resolve to an id. That id may point to another id in a different part of the same JSON object (Similar to a foreign key/primary key in a database). For each JSON path that is executed, the result (test, array, or object) is stored in a configurable variable and can be used in future JSON Paths. Previously stored values can be used either by substituting the stored variables in a new JSON Path, or by performing an operation.

Restrictions:

1. Currently, the only operation implemented is _.indexOf(), which allows someone to take one previously stored array and match the value from a stored variable, and return the index. With this index in hand, a new JSON Path can be executed.

2. All JSON Paths are performed on the same JSON object. Future improvements could allow JSON Paths to be run off of JavaScript objects created from previously resolved JSON Paths. However, this can also be achieved by the user calling resolvePaths() multiple times from the client side.

3. This module uses the json-path library (https://www.npmjs.org/package/json-path). All JSON Paths must follow the format specified in this library.

###Background

1. Open the default.json file and look at the resolvePaths property, and open the test/resolvePaths/DBQ_Metadata.json file, or look at:

    {
  "description":"The Client Role of Reference attribute",
  "path":"../cld:CommonData/vler:Client/nc:RoleOfPersonReference[/-s:ref]",
  "arrayIndex":"0",
  "saveVariable":"clientRoleOfReferenceAttribute"
    },
    {
  "description":"The Person ids",
  "path":"../cld:CommonData/nc:Person[*][/-s:id]",
  "saveVariable":"personIDs"
    }
    ,
    {
  "description":"Match the Client Role of Reference attribute with the Person id",
  "operation":"indexOf",
  "array":"personIDs",
  "value":"clientRoleOfReferenceAttribute",
  "saveVariable":"matchingPersonID"
    },
    {
  "description":"The SSN",
  "path":"../cld:CommonData/nc:Person[${matchingPersonID}]/nc:PersonSSNIdentification[/nc:IdentificationID]",
  "arrayIndex":"0",
  "saveVariable":"ssn",
  "returnVar":"ssn"
    }
    
      ]

1. The resolvePaths is an array of steps in processing the JSON file. The steps are executed in the order of the array. "description" is used in logging.

   "path" is the path passed to the json-path library.

   "arrayIndex" -OPTIONAL- is the value of the array index to limit the result from the resolved path.

   "saveVariable" is the variable to save the result from the call to json-path, after the array index is applied (if the array index was specified).

   Any number of steps can be added as separate objects as can be seen above.

   "operation" is the name of the operation to apply. Currently we support on operation "indexOf" which is mapped to underscore's _.indexOf(array, value, [isSorted]) The isSorted is not used.

   "array" is variable of the array passed to the operation (_.indexOf())

   "value" is value of the array passed to the operation (_.indexOf())

   In the third object above, the index is applied on the existing array. The result is saved to "saveVariable" as before. The next example is to resolve another json-path.In the third object above, the index is applied on the existing array. The result is saved to "saveVariable" as before. The next example is to resolve another json-path.

   ${variable} Previously stored variables can be replaced inside of a ${} string in the paths.

   "returnVar" The final step is to return a value to the API caller.

###functions

####resolvePaths.resolvePaths(aJSONobject, options)
returns a value (String, JavaScript object or array), where "aJSONobject" is your JavaScript object compatible with JSON, and the "options" holds the input array described in the background section.

utils module

A collection of small, common and reuseable json utilities.

###functions

####parseJSON (json) Able to parse both non-JSON, and also safely not parse valid JSON without erroring out.

examples/utils/utilsExample.js

var utils = require('json-utilities').utils; 
var fs = require('fs');
var sourceJSON = fs.readFileSync('./sourceJSON.json');

var parsedJson = utils.parseJSON( sourceJSON); 
console.log('parsedJson:', JSON.stringify(parsedJson));
console.log();

####getJSONPath (json, 'element') Returns an ordered array of a json path for any given element of a json object.

examples/utils/utilsExample.js

var jsonPath = utils.getJSONPath( sourceJSON, 'nc:IdentificationID'); 
console.log('jsonPath:', jsonPath);
console.log();

jsonPath: [ '0', 'nc:DocumentIdentification', 'nc:IdentificationID' ]

####javaScriptJSONPath (jsonPathStr) Returns a JavaScript JSON Path ready for use for gets and sets

examples/utils/utilsExample.js

var javaScriptJSONPath = utils.createJavaScriptJSONPath(jsonPath.toString());                       	
console.log('javaScriptJSONPath:', javaScriptJSONPath);
console.log();

javaScriptJSONPath: ['0']['nc:DocumentIdentification']['nc:IdentificationID']

API Development

Tools

Created with Nodeclipse (Eclipse Marketplace, site)

Nodeclipse is free open-source project that grows with your contributions.