quick-n-dirty-utils 0.0.14 → 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

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.
    */
@@ -540,12 +545,13 @@ var util = {
   },
 
   /**
-   * A function that will map a list of items to a JSON object which contains keys extracted from each item 
+   * 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} - a string key (can contain . for nested levels) or a lambda that does the extraction
-   * for each item.
+   * @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
@@ -576,6 +582,62 @@ var util = {
       }
     });
     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.14",
+  "version": "0.0.15",
   "description": "Little useful nuggets for accelerated web development",
   "scripts": {
     "build": "./node_modules/.bin/babel src --out-dir ./dist",