qtools-functional-library 1.1.11 → 1.1.13

package/README.md

@@ -1,28 +1,78 @@
-**qtools-functional-library**
-
-This is a collection of tools that allow chained operations on various Javascript datatypes. In each case, the primary operand is `this`. In most cases, the function takes parameteers to guide the operation. In all cases, `this` is returned for use by the next function in the chain. 
-
-Most of the functions included in this library (except, eg, qt.log()) are implemented on the prototype of the data type in question. For example, almost any element can take the .qtDump() function.
-
-- qtools-clone
-- qtools-get-by-property
-- qtools-includes-regex
-- qtools-log-output
-- qtools-merge
-- qtools-new-method-template
-- qtools-number-iterator
-- qtools-number-keys-to-array
-- qtools-object-sure-path
-- qtools-pass-through
-- qtools-pop
-- qtools-print-debug
-- qtools-template-replace
-- qtools-to-key-value-array
-- qtools-to-string
-
-NEW:
-
-- qtools-select-properties
-- qtools-map-properties
+## **qtools-functional-library**
+
+This is a collection of tools that allow chained operations on various Javascript datatypes. 
+
+In each case, the primary operand is `this`. In most cases, the function takes an argument with parameters to guide the operation. 
+
+**EG,**
+
+```
+const qt=require('qtools-functional-library');
+
+qt.help(); // this information and more
+
+const demo=({a:{b:"Hi from b"}})
+
+const one=demo
+    .qtGetSurePath('a.b')
+    .qtDump();//produces 'Hi from b [thisFilename.js]'
+
+console.log(one); //produces 'Hi from b'
+```
+
+### **Non-chain utilities:**
+
+- **qt.help**: Shows this information and more.
+- **qt.log**:    Writes log entry with suffix identifying the file that generated the output. (See qtLog below for chained version.)
+
+### **Get/Set values from an Array:**
+
+- **qtGetByProperty**: Operates on an array of objects. Retrieves one or more elements based on the value of an object property specified by a dotted path.
+
+- **qtPop**: Pops the last value off an array. If a default is supplied and there is nothing left on the list, that will be returned. Really good for ArrayOfObjects.qtPop({}).
+
+- **qtPush**: Pushes a value onto an array and returns the array (unlike normal .push() which returns the length of the array)
+
+- **qtLast**: Delivers the element that would have been pop'd but does not change the array. Default if none exists.
+
+- **qtFirst**: Delivers the element zero if it exists but does not change the array. Default if none exists.
+
+- **qtIncludesRegex**: Operations on a simple array of strings. Retrieves one or more elements based on an regEx match.
+
+### **Get/Set values in an Object (or array of Objects)**
+
+- **qtGetSurePath**: Gets the value of a property based on a dotted string path. No crash if intermediate elements are missing. Provides default. Predates and is prettier to use than optional chaining and supports setting the value.
+
+- **qtSetSurePath** Sets the value of a property based on a dotted string path. Creates intermediate elements if they are missing.
+
+- **qtSelectProperties**: Given an Object and an Array of Strings, filters the properties into a new Object with defaults for missing elements. Does the same for an Array of Objects.
+
+- **qtMapProperties**: Given an Object and a one level Object whose properties are functions, applies each function to the corresponding element. Does the same for an array of Objects.
+
+### **Array/Object Conversions:**
+
+- **qtClone**: Does a deep clone of an object or array.- qtNumberKeysToArray: Converts an object with properties that are numbers to an array, including subordinate properties.
+
+- **qtToKeyValueArray**: Converts an object to an array of objects of the form, ie, `{["1"]:'one', ["2"]:'two'} => ['one', 'two']`
+
+- **qtMerge**: Deep merge of two objects including array propterties.
+
+- **qtToString**: Joins an array with prefix, suffix and separator. Pretty much the same as .join().
+
+### **Array/Object Template Replacement:**
+
+- **qtTemplateReplace**: Takes Object and a `<!template!>` String ()either can be 'this' or the argument). Substitutes from the object properties into the string. If the 'this' is an array of Objects, it does it to all of them.
+
+### **Output:**
+
+- **qtDump**: Prints 'this' and returns it. Good for debugging complicated chains.
+
+- **qtLog**: Logs message by applying 'this' into the argument which is a <!template!> string. Appends calling file name.
+
+### **Misc:**
+
+- **qtPassThrough**: Sits in a declarative chain and executes an arbitrary function. It returns 'this' regardless of what the function does. 'this' is available to the function.
+
+- **qtIterate**: Operates on a number. EG, (5).qtStart(7).qtIncrement(3).qtIterate(item=>item*100)
 
 DESCRIPTION

package/lib/qtools-number-keys-to-array/test.js

@@ -5,24 +5,24 @@
 const moduleFunction = function(args) {
 	//this module is initialized with parameters spec'd in the main function module
 	
-	const completeStepActual = ({verbose=false, logErrors=false, moduleName}) => (
-		methodName,
-		thisStepMessage,
-		thisStepResult,
-		thisStepEvalFunction
-	) => {
-
+	const completeStepActual = ({
+		verbose = false,
+		logErrors = false,
+		moduleName
+	}) => (methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) => {
 		const thisStepPass = thisStepEvalFunction(thisStepResult);
-		
+
 		if (logErrors && !thisStepPass) {
 			console.log(`FAIL TEST: ${thisStepMessage} in ...${moduleName}`);
 		}
 		if (verbose) {
-			console.log(`Result for: ${methodName} (${thisStepPass?'PASS':'FAIL'}):`);
+			console.log(
+				`Result for: ${methodName} (${thisStepPass ? 'PASS' : 'FAIL'}):`
+			);
 			console.dir(thisStepResult);
 			console.log('\n\n');
 		}
-		
+
 		return passingTests && thisStepPass;
 	};
 
@@ -40,82 +40,133 @@ const moduleFunction = function(args) {
 	
 	
 	const testArray = {
-['0']:'zero',
-['1']:'one',
-['4']:'four',
-a:'b'
-
-}
+		['0']: 'zero',
+		['1']: 'one',
+		['4']: 'four',
+		a: 'b'
+	};
 
 	
 	
 	const testArray2 = {
-['0']:'zero',
-['1']:'one',
-['4']:'four',
-a:'b',
-subArray:{['0']:'zeroX',
-['1']:'oneX',
-['4']:'fourX'},
-
-}
+		['0']: 'zero',
+		['1']: 'one',
+		['4']: 'four',
+		a: 'b',
+		subArray: {
+			['0']: 'zeroX',
+			['1']: 'oneX',
+			['4']: 'fourX'
+		}
+	};
 
-const emptyArray={}
+	const emptyArray = {};
 	
 
 	//TEST ITEM ------------------------------------------------------
-	methodName='qtNumberKeysToArray'
-	thisStepMessage = "test #1, result is wrong, holes or length are wrong";
-	thisStepResult = testArray[methodName]({collapseHoles:false, omitNonNumeric:true});
-	thisStepEvalFunction = item => item=(item.length==5 && typeof(item[2])=='undefined' && typeof(item[3])=='undefined');
+	methodName = 'qtNumberKeysToArray';
+	thisStepMessage = 'test #1, result is wrong, holes or length are wrong';
+	thisStepResult = testArray[methodName]({
+		collapseHoles: false,
+		omitNonNumeric: true
+	});
+	thisStepEvalFunction = item =>
+		(item =
+			item.length == 5 &&
+			typeof item[2] == 'undefined' &&
+			typeof item[3] == 'undefined');
 	passingTests =
-		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
-		passingTests;
+		completeStep(
+			methodName,
+			thisStepMessage,
+			thisStepResult,
+			thisStepEvalFunction
+		) && passingTests;
 	
 	
 	//TEST ITEM ------------------------------------------------------
-	methodName='qtNumberKeysToArray'
-	thisStepMessage = "test #2, result is wrong, has holes or length is wrong";
-	thisStepResult = testArray[methodName]({collapseHoles:true, omitNonNumeric:true});
-	thisStepEvalFunction = item => item=(item.length==3 && item.reduce((item, result)=>(typeof(item!='undefined') && result), true));
+	methodName = 'qtNumberKeysToArray';
+	thisStepMessage = 'test #2, result is wrong, has holes or length is wrong';
+	thisStepResult = testArray[methodName]({
+		collapseHoles: true,
+		omitNonNumeric: true
+	});
+	thisStepEvalFunction = item =>
+		(item =
+			item.length == 3 &&
+			item.reduce(
+				(item, result) => typeof (item != 'undefined') && result,
+				true
+			));
 	passingTests =
-		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
-		passingTests;
+		completeStep(
+			methodName,
+			thisStepMessage,
+			thisStepResult,
+			thisStepEvalFunction
+		) && passingTests;
 	
 	
 	
 	
 	//TEST ITEM ------------------------------------------------------
-	methodName='qtNumberKeysToArray'
-	thisStepMessage = "test #3, result is wrong, non-numeric element is missing or length is wrong";
-	thisStepResult = testArray[methodName]({collapseHoles:true, omitNonNumeric:false});
-	thisStepEvalFunction = item => item=(item.length==4 && typeof(item[3])=='object');
+	methodName = 'qtNumberKeysToArray';
+	thisStepMessage =
+		'test #3, result is wrong, non-numeric element is missing or length is wrong';
+	thisStepResult = testArray[methodName]({
+		collapseHoles: true,
+		omitNonNumeric: false
+	});
+	thisStepEvalFunction = item =>
+		(item = item.length == 4 && typeof item[3] == 'object');
 	passingTests =
-		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
-		passingTests;
+		completeStep(
+			methodName,
+			thisStepMessage,
+			thisStepResult,
+			thisStepEvalFunction
+		) && passingTests;
 	
 
 	
 	
 	
 	//TEST ITEM ------------------------------------------------------
-	methodName='qtNumberKeysToArray'
-	thisStepMessage = "test #4, subordinate element was not converted properly";
-	thisStepResult = testArray2[methodName]({collapseHoles:true, omitNonNumeric:false});
-	thisStepEvalFunction = item => item=(item.length==5 && typeof(item[4])=='object' && item[4].value.length==3);
+	methodName = 'qtNumberKeysToArray';
+	thisStepMessage = 'test #4, subordinate element was not converted properly';
+	thisStepResult = testArray2[methodName]({
+		collapseHoles: true,
+		omitNonNumeric: false
+	});
+	thisStepEvalFunction = item =>
+		(item =
+			item.length == 5 &&
+			typeof item[4] == 'object' &&
+			item[4].value.length == 3);
 	passingTests =
-		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
-		passingTests;
+		completeStep(
+			methodName,
+			thisStepMessage,
+			thisStepResult,
+			thisStepEvalFunction
+		) && passingTests;
 	
 	
 	//TEST ITEM ------------------------------------------------------
-	methodName='qtNumberKeysToArray'
-	thisStepMessage = "test #5, empty object returns empty array";
-	thisStepResult = emptyArray[methodName]({collapseHoles:true, omitNonNumeric:false});
-	thisStepEvalFunction = item => item=(item.length===0);
+	methodName = 'qtNumberKeysToArray';
+	thisStepMessage = 'test #5, empty object returns empty array';
+	thisStepResult = emptyArray[methodName]({
+		collapseHoles: true,
+		omitNonNumeric: false
+	});
+	thisStepEvalFunction = item => (item = item.length === 0);
 	passingTests =
-		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
-		passingTests;
+		completeStep(
+			methodName,
+			thisStepMessage,
+			thisStepResult,
+			thisStepEvalFunction
+		) && passingTests;
 	
 	
 	

package/lib/qtools-pop/qtools-pop.js

@@ -102,6 +102,41 @@ var moduleFunction = function(args = {}) {
 			test
 		};
 	};
+	//fourth method definition function ==========================
+	const fourthMethodFunction = commonFunctions => {
+		const methodName = 'qtFirst';
+		const description = `operand.qtFirst(value) gets element zero or default`;
+		const supportedTypeList = [Array];
+
+		const method = () =>
+			function(value) {
+				const inData = this;
+				if (typeof inData.length == 'undefined') {
+					throw 'array.qtFirst(defaultValue=undefined) works for Arrays only';
+				}
+				const arrayValue = inData[0]?inData[0]:void('');
+				const result =
+					typeof arrayValue != 'undefined' ? arrayValue : defaultValue;
+				return result;
+			};
+
+		const test = args => {
+			return require('./test.js')({
+				...args,
+				...{
+					moduleName: module.id.replace(module.path, '')
+				}
+			});
+		};
+
+		return {
+			methodName,
+			description,
+			supportedTypeList,
+			method,
+			test
+		};
+	};
 	
 	const functionObject = new Map(); // prettier-ignore
 	const addFunction = definition => {
@@ -130,6 +165,7 @@ var moduleFunction = function(args = {}) {
 	addFunction(firstMethodFunction());
 	addFunction(secondMethodFunction());
 	addFunction(thirdMethodFunction());
+	addFunction(fourthMethodFunction());
 
 	this.addToPrototype = addToPrototypeActual(functionObject);
 	

package/lib/qtools-pop/test.js

@@ -96,6 +96,15 @@ const moduleFunction = function(args) {
 		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
 		passingTests;
 	
+	//TEST ITEM ------------------------------------------------------
+	methodName='qtFirst'
+	thisStepMessage = "element was not added";
+	thisStepResult = testArray[methodName]();
+	thisStepEvalFunction = item => (item=='allocute' && item.length==2);
+	passingTests =
+		completeStep(methodName, thisStepMessage, thisStepResult, thisStepEvalFunction) &&
+		passingTests;
+	
 	
 	
 

package/lib/qtools-template-replace/qtools-template-replace.js

@@ -8,7 +8,6 @@ var moduleFunction = function(args = {}) {
 
 	const baseReplacementFunction = (replaceObject, template, options) => {
 		const { transformations = {}, leaveUnmatchedTagsIntact = true } = options;
-
 		replaceObject = replaceObject.qtClone().qtMerge(transformations);
 
 		const tmp = template.match(/<!.*?!>/g);
@@ -45,6 +44,8 @@ var moduleFunction = function(args = {}) {
 	// prettier-ignore
 	const stringCallsObject = (item, arg) => arg instanceof Object && typeof item == 'string';
 	// prettier-ignore
+	const stringCallsArrayOfObjects = (item, arg) => arg instanceof Array && typeof item == 'string';
+	// prettier-ignore
 	const arrayOfStringsCallsObject = (item, arg) => arg instanceof Object && item instanceof Array && item.filter(item => typeof item == 'string').qtPop(false) ? true : false;
 
 	//first method definition function ==========================
@@ -69,6 +70,8 @@ var moduleFunction = function(args = {}) {
 					return this.map(item => baseReplacementFunction(item, arg, options));
 				} else if (objectCallsString(this, arg)) {
 					return baseReplacementFunction(this, arg, options);
+				} else if (stringCallsArrayOfObjects(this, arg)) {
+					return arg.map(item => baseReplacementFunction(item, this, options));
 				} else if (stringCallsObject(this, arg)) {
 					return baseReplacementFunction(arg, this, options);
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qtools-functional-library",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "Useful additions to JS prototypes to facilliate chainable, functional (mostly) style. Also make life more convenient.\"",
   "main": "qtools-functional-library.js",
   "scripts": {

package/qtools-functional-library.js

@@ -19,7 +19,7 @@ const commonFunctions = {
 			methods.push(methodName);
 			documentation.push({
 				name: methodName,
-				description: `${methodName}: ${functionItem.description}`,
+				description: `${functionItem.description}`,
 				supportedTypeList
 			});
 
@@ -226,21 +226,32 @@ const addMorePrototypes = () => {
 
 addMorePrototypes();
 
-const helpActual = docList => (queryString = '') => {
-	//someday turn this into a report instead of a JSON dump, add support for item.suppressHelpListing for qtLog_AddCallableMethods
-	let outList;
+const helpActual = docList => (options={}) => {
+
+	const {printOutput=true, sendJson=false, queryString='.*'}=options;
+
+	let rawList;
 	if (!queryString) {
-		outList = docList;
+		rawList = docList;
 	} else {
-		outList = docList.filter(item => {
+		rawList = docList.filter(item => {
 			const regex = new RegExp(queryString, 'i');
 			const result = JSON.stringify(item).match(regex);
 			return result;
 		});
 	}
-	// 	const util=require('util');
-	// 	util.inspect(docList, { depth: null, maxArrayLength: null }).qtDump('qtFuncionalLib Documentation');
-	return outList;
+
+	let outArray=[];
+	rawList.forEach(item=>{
+		outArray=outArray.concat(item);
+	});
+	
+	const outString='<!name!>: <!description!> (<!supportedTypeList!>) '.qtTemplateReplace(outArray).join('\n');
+
+	if (printOutput){
+		console.log(outString);	
+	}
+	return outString;
 };
 
 const testActual = testList => (args={}) => {