qtools-functional-library 1.1.12 → 1.1.13

package/README.md

@@ -1,29 +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: Does a deep clone of an object or array.
-- qtools-get-by-property: Operates on an array of objects. Retrieves one or more elements based on the value of an object property specified by a dotted path.
-- qtools-includes-regex: Operations on a simple array of strings. Retrieves one or more elements based on an regEx match.
-- qtools-log-output: Substitutes properties into a <!template!> string and send to log. (Note to self, verify array operation)
-- qtools-merge: Deep merge of two objects including array propterties.
-- qtools-number-iterator: Operates on a number. EG, (5).qtStart(7).qtIncrement(3).qtIterate(item=>item*100)
-- qtools-number-keys-to-array: Converts an object with properties that are numbers to an array, including subordinate properties.
-- qtools-object-sure-path: Gets or Sets 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.
-- qtools-pass-through: 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.
-- qtools-pop: 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({}).
-- qtools-qtLast: Delivers the element that would have been pop'd but does not change the array.
-- qtoolspush: Pushes a value onto an array and returns the array (unlike normal .push() which returns the length of the array)
-- 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-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.12",
+  "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={}) => {