quick-n-dirty-utils 1.0.4 → 1.0.5

package/README.md

@@ -505,6 +505,40 @@ const items = [
 ...
 ```
 
+#### `groupObjects(objects, key = null, count = false)`
+
+Takes a list of objects and calls the provided key(obj) function on each obj in objects and stores the key in a JSON
+object with the value being either a list of all the values matching that key (count = false) or the number of values
+matching the key (if count = true).
+
+
+```javascript
+import { util } from "quick-n-dirty-utils"
+const objects = [{axis: "x", value: 5}, {axis: "x", value: 3}, {axis: "y", value: 17}]
+const grouped = util.groupObjects(objects, (obj) => obj.axis, true)
+// returns {x: 2, y: 1}
+const grouped = util.groupObjects(objects, (obj) => obj.axis, false)  // don't use count, but return values instead
+// returns {x: [{axis: "x", value: 5}, {axis: "x", value: 3}], y: [{axis: "y", value: 17}]}
+```
+
+#### `sortGrouping(grouping, reverse = true, countKey = "total", countExec = null)`
+
+Takes a grouping (see `groupObjects`), which is a JSON object with values either being numbers of arrays. The function
+will convert this JSON object in a list of JSON objects with keys "key", "value" and whatever is specified as `countKey`
+
+```javascript
+import { util } from "quick-n-dirty-utils"
+const objects = [{axis: "x", value: 5}, {axis: "x", value: 3}, {axis: "y", value: 17}]
+const grouping = util.groupObjects(objects, (obj) => obj.axis, false)  // returns { x: [..], y: [..] }
+
+// sort grouping by the sum of "value" values in each list of items in ascending order and store the sum as "total"
+const sorted = util.sortGrouping(grouping, true, "total", (items) => util.sum(items.map(i => i.value)))
+// returns [
+//      {key: "x", value: [{axis: "x", value: 5}, {axis: "x", value: 3}], "total": 8},
+//      {key: "y", value: [{axis: "y", value: 17}], "total": 17},
+// ]
+```
+
 ### Others
 
 #### `exportToJson(objectData, filename)`

package/dist/functions.js

@@ -64,6 +64,8 @@ var qndUtils = {
     fulfilled: "_FULFILLED",
     rejected: "_REJECTED"
   },
+  // sort directions (ASC / DESC)
+  SORT_DIRECTIONS: SORT_DIRECTIONS,
 
   /**
    * Uses the hard-coded date format to format the provided date. If no valid date is provided, null is returned.
@@ -672,10 +674,12 @@ var qndUtils = {
   /**
    * Finds out if an array of values occurs in another array of values. This is useful for filtering lists, which
    * have multiple values for an attribute and you want the user to be able to filter by some of the values.
-   * @param {Array} values - a list of values that you want to check match some items in matchAgainst. If empty, 
+   * @param {Array} values - a list of values that you want to check match some items in matchAgainst. If empty,
    * false will be returned
    * @param {Array} matchAgainst - a list of selected filters. If the array is empty, false will be returned.
    * @param {Number} minMatch - the number of items in matchAgainst that have to be in the values.
+   * @returns {boolean} a boolean indicating, whether enough items in values match against the list of matchAgainst,
+   * where "enough" is determined by the minMatch argument.
    */
   arrayMatch: function arrayMatch() {
     var values = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
@@ -760,13 +764,84 @@ var qndUtils = {
   },
 
   /**
-   * Returns all unique values in a list of values. All duplicates will be removed. This does not modify the original 
+   * Returns all unique values in a list of values. All duplicates will be removed. This does not modify the original
    * list.
    * @param {Array} values - a list of values
    * @returns {Array} a list of unique values
    */
   uniqueValues: function uniqueValues(values) {
     return _toConsumableArray(new Set(values));
+  },
+  groupObjects: function groupObjects(objects) {
+    var key = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
+    var count = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
+
+    /**
+     * Groups a list of items together by a key determined from the list item and supports counting items as well.
+     * @param {Array} objects - a list of values (either simple or complex objects)
+     * @param {function} key - an optional function that is used to determine the key from the item. If not
+     * provided, the entire item is used as key (this only works if the items contained in the list of objects are
+     * valid json keys)
+     * @param {boolean} count - a flag indicating whether to collect a list of items or the number of items (true)
+     * @returns {object} a json object with the keys as keys and the count (if count is true) or the list of values
+     * as values.
+     */
+    var result = {};
+    objects.forEach(function (item) {
+      var k = key == null ? item : key(item);
+
+      if (result[k] == null) {
+        result[k] = count ? 0 : [];
+      }
+
+      if (count === true) {
+        result[k] += 1;
+      } else {
+        result[k].push(item);
+      }
+    });
+    return result;
+  },
+  sortGrouping: function sortGrouping(grouping) {
+    var reverse = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : true;
+    var countKey = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : "total";
+    var countExec = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : null;
+
+    /**
+     * Sorts a grouping by a counter/total value determined for each value of the input.
+     * @param {object} grouping - a json object with key > [values]
+     * @param {boolean} reverse - if true, the items will be sorted from highest to lowest (default).
+     * @param {str} countKey - the result will contain a list of json objects, with the countKey providing the json
+     * key used to store the total/counter value by which the list is sorted.
+     * @param {function} countExec - an optional lambda/function that is used to determine the counter value for
+     * each key. The countExec gets one parameter, which is the list of values for each key and the result needs to
+     * be numeric.
+     * @returns {Array} a list of json objects, where each object contains keys: "key" (storing the key from the
+     * grouping), "value" (storing the list of values underneath the key), "total" (or whatever is provided as
+     * countKey - storing either the length of the list of values, if countExec is null or the counter value
+     * determined by the countExec function)
+     */
+    var result = [];
+    Object.keys(grouping).forEach(function (k) {
+      var v = grouping[k];
+      var count = v; // default case, if values are numbers
+
+      if (Array.isArray(v)) {
+        // list provided, either measure the length or call the count exec function on the list
+        count = countExec == null ? v.length : countExec(v);
+      }
+
+      var resultItem = {
+        key: k,
+        value: v
+      };
+      resultItem[countKey] = count;
+      result.push(resultItem);
+    }); // sorting
+
+    return result.sort(function (a, b) {
+      return reverse === true ? b[countKey] - a[countKey] : a[countKey] - b[countKey];
+    });
   }
 };
 var _default = qndUtils;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quick-n-dirty-utils",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Little useful nuggets for accelerated web development",
   "scripts": {
     "build": "./node_modules/.bin/babel src --out-dir ./dist",