quick-n-dirty-utils 0.0.12 → 0.0.15

package/README.md

@@ -218,6 +218,43 @@ fetch("http://myurl.com", {
     })
  ```
 
+
+#### React State Handlers
+
+When a React component uses a state variable to store a list of items any create/update/delete operation
+ will have to modify that state variable. To help integrate new/updated items or remove items, the 
+ following 2 functions are available:
+
+```javascript
+import util from "quick-n-dirty-utils"
+import React from "react"
+
+class MyComp extends React.Component {
+    constructor(props) {
+        super(props)
+        this.state = { myList: [] }
+    }
+    saveItem(item) {
+        // doesn't matter if add or update
+        this.setState(oldState => ({
+            ...oldState,
+            myList: util.integrateDbItem(oldState.myList, item),
+        }))
+    }
+    deleteItem(itemId) {
+        this.setState(oldState => ({
+            ...oldState,
+            myList: util.removeDbItem(oldState.myList, itemId),
+        }))
+    }
+}
+```
+
+Both functions will use the MongoDB convention and use the JSON key `_id` to match items. You can 
+ override that by providing a 3rd parameter: `util.integrateDbItem(oldState.myList, item, "uid")` 
+ and `util.removeDbItem(oldState.myList, itemId, "uid")` if for example your JSON key holding the
+ unique ID is called `uid`.
+
 #### Login
 
 The login functions (including `getAuthJsonHeader()` and `getAuthHeader()`) assume that you use the browser's 
@@ -355,6 +392,13 @@ The colors are defaulted to blue (1.0) -> white (0.5) -> red (0.0) and are provi
 
 Static field providing a `colors` setting for the `getTriColor(..)` function for red -> yellow -> green.
 
+#### `hexToRgb(hexValue, alpha)`
+
+Converts a colour provided as hexadecimal string into an RGB string, like `rgb(255, 255, 255)` that can
+ be used in CSS. It allows an optional `alpha` parameter (default `null`), which will create a string 
+ like `rgba(255, 255, 255, 0.3)` for an `alpha = 0.3`. The `hexValue` can be provided with or without the 
+ `#` prefix.
+
 ### Sorting
 
 This library introduces a way to sort lists. It has capabilties to sort in ascending or descending order
@@ -527,3 +571,85 @@ const MAPPING = {
 
 const DEFAULT_VIEW = util.keyLookup(MAPPING, MAPPING.INVOICE) // this will be "INVOICE"
 ```
+
+#### `jsonGet(object, key)`
+
+This simple function has the purpose to access nested JSON objects without 
+ having to manually check for null at each step.
+
+Example:
+
+```javascript
+import util from "quick-n-dirty-utils"
+
+const myObject = {
+    foo: {
+        bar: {
+            test: 1,
+        },
+    },
+}
+
+util.jsonGet(myObject, "foo")  // will return { bar: { test: 1 } }
+util.jsonGet(myObject, "foo.bar.test") // will return 1
+util.jsonGet(myObject, "foo.test.bar")  // will return null
+```
+
+#### `mapListToKeyObject(list, keyOrFunction)`
+
+This function allows to map a list of uniform items to a flat JSON object,
+ where each object will be stored under a key which is determined from the
+ object by accessing a string key or executing a function on that item.
+
+The result will be a JSON object. Underneath each key, it will store 
+ either a single item extracted using the key or function passed or a list
+ of item, if multiple items map to the same key.
+
+Example:
+
+```javascript
+import util from "quick-n-dirty-utils"
+
+const myList = [
+    { _id: "a", name: "foo", level: 1, order: 1 },
+    { _id: "b", name: "bar", level: 2, order: 2 },
+    { _id: "c", name: "test", level: 1, order: 3 },
+]
+
+// using a unique key
+const result1 = util.mapListToKeyObject(myList, "_id")
+/*
+ * will return:
+ * {
+ *   "a": { _id: "a", name: "foo", level: 1, order: 1 },
+ *   "b": { _id: "b", name: "bar", level: 2, order: 2 },
+ *   "c": { _id: "c", name: "test", level: 1, order: 3 },
+ * }
+ */
+
+// using a key that has duplicates
+const result2 = util.mapListToKeyObject(myList, "level")
+/*
+ * will return:
+ * {
+ *   1: [
+ *     { _id: "a", name: "foo", level: 1, order: 1 },
+ *     { _id: "c", name: "test", level: 1, order: 3 },
+ *   ],
+ *   2: { _id: "b", name: "bar", level: 2, order: 2 },
+ * }
+ */
+
+// using a lambda
+const result3 = util.mapListToKeyObject(myList, item => item[level] + item[order])
+/*
+ * will return:
+ * {
+ *   2: { _id: "a", name: "foo", level: 1, order: 1 },
+ *   4: [
+ *     { _id: "b", name: "bar", level: 2, order: 2 },
+ *     { _id: "c", name: "test", level: 1, order: 3 },
+ *   ],   
+ * }
+ */
+```

package/dist/util.js

@@ -430,9 +430,14 @@ var util = {
 
   /**
    * Sums up all the values in the provided list
-   * @param {Array} list
+   * @param {Array} list - a list of numbers
+   * @returns {Number} the sum of all the items in the list or 0 if the list is empty.
    */
   sum: function sum(list) {
+    if (list.length === 0) {
+      return 0;
+    }
+
     return list.reduce(function (a, b) {
       return a + b;
     }, 0);
@@ -457,9 +462,9 @@ var util = {
 
   /**
    * Returns an inversed JSON object, where every value becomes the key and maps to its original key.
-   * @param {object} jsonObject - a flat JSON object, with simple keys and simple values (boolean, 
+   * @param {object} jsonObject - a flat JSON object, with simple keys and simple values (boolean,
    * string, number are supported)
-   * @param {boolean} showWarning - optional flag to print out console warnings in case any key/value 
+   * @param {boolean} showWarning - optional flag to print out console warnings in case any key/value
    * pair cannot be mapped or if the JSON object contains duplicates - default = true
    * @returns {object} a JSON object which maps from each value of the input to the key.
    */
@@ -505,6 +510,134 @@ var util = {
     var showWarning = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : true;
     var reverse = this.reverseMapping(jsonMapping, showWarning);
     return reverse[lookupValue];
+  },
+
+  /**
+   * A function to savely access nested JSON keys in objects. This will handle deeper levels and especially
+   * if keys higher up in the hierarchy are not set.
+   * @param {Object} object - a JSON object
+   * @param {key} key - a string that can include dots (.) for nested JSON keys
+   * @returns {Object} null if the key does not exist in the object or the resolved value
+   */
+  jsonGet: function jsonGet(object, key) {
+    if (object == null) {
+      return null;
+    }
+
+    if (!key.includes(".")) {
+      // simply return the value
+      return object[key];
+    } // split the key and initialise current object
+
+
+    var current = object;
+    var keys = key.split("."); // iterate through keys navigating through
+
+    keys.forEach(function (k) {
+      if (current == null) {
+        return;
+      }
+
+      current = current[k];
+    }); // return the final value after iterating through all keys
+
+    return current;
+  },
+
+  /**
+   * A function that will map a list of items to a JSON object which contains keys extracted from each item
+   * and the value is the object from that list with that key. If multiple values map to the same keys an array
+   * of objects will be mapped to that key.
+   * @param {Array} list - a list of items
+   * @param {string|function} keyOrFunction - a string key (can contain . for nested levels) or a lambda that does
+   * the extraction for each item.
+   * @returns {Object} a json object mapping from key to an item or list of items
+   */
+  mapListToKeyObject: function mapListToKeyObject(list, keyOrFunction) {
+    // check if it's a simple key mapping or lambda
+    var lambda = ["number", "string"].includes(_typeof(keyOrFunction)) ? function (obj) {
+      return obj[keyOrFunction];
+    } : keyOrFunction;
+    var result = {};
+
+    if (list == null || keyOrFunction == null || list.forEach == null) {
+      return result;
+    }
+
+    list.forEach(function (item) {
+      var key = lambda(item);
+
+      if (result[key] == null) {
+        // first item for this key
+        result[key] = item;
+      } else {
+        // multiple items for the same key (might have to convert to array)
+        if (!Array.isArray(result[key])) {
+          // not yet an array, convert the old item stored there
+          result[key] = [result[key]];
+        } // push the new item
+
+
+        result[key].push(item);
+      }
+    });
+    return result;
+  },
+
+  /**
+   * Adds or updates an item in a list of items and returns the updated list. This is useful for React state updates.
+   * @param {Array} list - a list of items
+   * @param {Object} item - a JSON object to be added to the list or updated, if it already exists
+   * @param {string} idKey - the JSON key pointing to the element ID of the item and items in the list
+   * @returns {Array} the updated array with the provided `item` either added or updated.
+   */
+  integrateDbItem: function integrateDbItem(list, item) {
+    var idKey = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : "_id";
+    var index = list.map(function (i) {
+      return i[idKey];
+    }).indexOf(item[idKey]);
+
+    if (index === -1) {
+      list.push(item);
+    } else {
+      list[index] = item;
+    }
+
+    return list;
+  },
+
+  /**
+   * Removes an item from a list by referring to the unique item id. This is a simple id filter. Useful for React state updates.
+   * @param {Array} list - a list of items
+   * @param {string} itemId - the id of the item to remove
+   * @param {string} idKey - the JSON key pointing to the element ID of the item and items in the list
+   * @returns {Array} the provided list minus the element with the id provided.
+   */
+  removeDbItem: function removeDbItem(list, itemId) {
+    var idKey = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : "_id";
+    return list.filter(function (item) {
+      return item[idKey] !== itemId;
+    });
+  },
+
+  /**
+   * Translates a hex colour code into an RGB string. If alpha is provided, it will return an RGBA string. The string can be used in CSS styles
+   * @param {string} hexValue - the hex value of colour; can be provided with or without the # and as 3 or 6 digit color
+   * @param {Number} alpha - optional: if provided an RGBA (transparency) colour will be returned
+   * @returns {string} a colour string usable in colour definitions in CSS
+   */
+  hexToRgb: function hexToRgb(hexValue) {
+    var alpha = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
+    var hex = hexValue.replace("#", "");
+    var r = parseInt(hex.length === 3 ? hex.slice(0, 1).repeat(2) : hex.slice(0, 2), 16);
+    var g = parseInt(hex.length === 3 ? hex.slice(1, 2).repeat(2) : hex.slice(2, 4), 16);
+    var b = parseInt(hex.length === 3 ? hex.slice(2, 3).repeat(2) : hex.slice(4, 6), 16);
+
+    if (alpha != null) {
+      return "rgba(".concat(r, ", ").concat(g, ", ").concat(b, ", ").concat(alpha, ")");
+    }
+
+    return "rgb(".concat(r, ", ").concat(g, ", ").concat(b, ")");
   }
 };
 var _default = util;

package/package.json

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