quick-n-dirty-utils 0.0.13 → 1.0.0

package/README.md

@@ -31,12 +31,12 @@ const range = util.range(1, 10)
 
 ### Date / Time
 
-All date / time functions use `moment` (MomentJS, the de-factor standard library for date/time) to provide the 
+All date / time functions use `luxon` (Luxon, the de-factor standard library for date/time) to provide the 
 functionality.
 
 #### `formatDate(date, format)`
-Converts a `Date` object or `moment` object into a string for quick display of dates **without** a time component.
-The default format is `YYYY-MM-DD`.
+Converts a `Date` object, Unix timestamp or `luxon.DateTime` object into a string for quick display of dates 
+**without** a time component. The default format is `yyyy-MM-dd`.
 
 Example:
 
@@ -50,15 +50,15 @@ const reactComponent = props => (
         <div>{util.formatDate(new Date())}</div>
         
         {/* prints out a date like 18/02/20 */}
-        <div>{util.formatDate(new Date(), "DD/MM/YY")}</div>
+        <div>{util.formatDate(new Date(), "dd/MM/yy")}</div>
     </div>
 )
 ```
 
-#### `formatDateTime(dateTime)`
-Converts a `Date` object or `moment` object into a string for quick display of dates **with** a time component. If you
-require a custom format, you can simply use `formatDate(new Date(), "YY-MM-DD hh:mm:ss)`. The default format is
-`DD/MM/YY hh:mm`
+#### `formatDateTime(dateTime, format)`
+Converts a `Date` object, Unix timestamp or `luxon.DateTime` object into a string for quick display of dates 
+**with** a time component. If you require a custom format, you can provide this. The default format is
+`dd/MM/yy T` (e.g. 31/12/22 16:43)
 
 Example:
 
@@ -76,8 +76,8 @@ const reactComponent = props => (
 
 #### `applyTimeZoneOffset(timestamp, serverOffsetMin)`
 Used to offset mismatching server/client time zones in regards to timestamps. If your server provides Unix timestamps, 
-but is located in a different timezone, then simply printing out those timestamps (as `moment`/`Date`) will print the
-time in the clients (browser) time zone, not the server time zone. Example: Your server provides timestamps for events 
+but is located in a different timezone, then simply printing out those timestamps (as `luxon.DateTime`/`Date`) will print 
+the time in the clients (browser) time zone, not the server time zone. Example: Your server provides timestamps for events 
 and the event occurred at midnight, but you are located 2 hours behind the server's time zone. If you use that timestamp
 and print out the date (e.g. `util.formatDateTime(new Date(myTimestamp))`), it will show you 10pm, rather than midnight.
 Depending on the application, it might be useful to retain the local time.
@@ -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 → functions.js}

@@ -5,9 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports["default"] = void 0;
 
-var _moment = _interopRequireDefault(require("moment"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+var _luxon = require("luxon");
 
 function _typeof(obj) { "@babel/helpers - typeof"; if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }; } return _typeof(obj); }
 
@@ -26,9 +24,9 @@ function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { va
 function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 
 // default date format
-var DATE_FORMAT = "YYYY-MM-DD"; // default date/time format
+var DATE_FORMAT = "yyyy-MM-dd"; // default date/time format
 
-var DATE_TIME_FORMAT = "DD/MM/YY hh:mm"; // localStorage key uses to store the auth token
+var DATE_TIME_FORMAT = "dd/MM/yy T"; // localStorage key uses to store the auth token
 
 var LS_AUTH_KEY = "auth_token";
 var SORT_DIRECTIONS = {
@@ -39,7 +37,7 @@ var SORT_DIRECTIONS = {
  * Utilities used across components
  */
 
-var util = {
+var qndUtils = {
   /**
    * Default date format for quick display
    */
@@ -61,18 +59,54 @@ var util = {
 
   /**
    * Uses the hard-coded date format to format the provided date. If no valid date is provided, null is returned.
-   * @param {(object|string)} date: the date to format, provided either as string or moment object. If a string is
-   * provided, that string needs to be parsable by moment
-   * @param {string} dateFormat: the date format to be used by moment to serialise the date, default "YY-MM-DD"
+   * @param {(object|string)} date: the date to format, provided either as string or Luxon object. If a string is
+   * provided, that string needs to be parsable by Luxon
+   * @param {string} dateFormat: the date format to be used by Luxon to serialise the date, default "yyyy-MM-dd"
    * @returns {String} the formatted string or null, if the provided date string or object is not valid or cannot be
    * parsed.
    */
   formatDate: function formatDate(date) {
     var dateFormat = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : DATE_FORMAT;
-    var d = (0, _moment["default"])(date);
 
-    if (d.isValid()) {
-      return d.format(dateFormat);
+    // handling JS date objects
+    if (date instanceof Date) {
+      return this.formatDate(_luxon.DateTime.fromJSDate(date));
+    } // handling unix timestamps (guessing s or ms)
+
+
+    if (typeof date === "number") {
+      if (date < 5000000000) {
+        // otherwise would be year 2128+
+        return this.formatDate(_luxon.DateTime.fromSeconds(date), dateFormat);
+      } // doesn't work for dates before 28 Feb 1970
+
+
+      return this.formatDate(_luxon.DateTime.fromMillis(date), dateFormat);
+    } // handling string date/times
+
+
+    if (typeof date === "string") {
+      // attempt to parse
+      var functions = [_luxon.DateTime.fromISO, _luxon.DateTime.fromSQL, _luxon.DateTime.fromRFC2822];
+
+      for (var i = 0; i < functions.length; i += 1) {
+        var parsedDate = functions[i](date);
+
+        if (parsedDate.isValid) {
+          return this.formatDate(parsedDate, dateFormat);
+        }
+      }
+
+      throw Error("Provided string date could not be detected, please convert to Luxon DateTime before formatting");
+    } // handling momentjs objects
+
+
+    if (date._isAMomentObject != null && date.unix != null) {
+      return this.formatDate(date.unix(), dateFormat);
+    }
+
+    if (date.isValid) {
+      return date.toFormat(dateFormat);
     }
 
     return null;
@@ -80,13 +114,15 @@ var util = {
 
   /**
    * Uses a hard-coded date/time format to format the provided date. If no valid date is provided, null is returned.
-   * @param {(object|string)} date: the date to format, provided either as string or moment object. If a string is
-   * provided, that string needs to be parsable by moment
+   * @param {(object|string)} date: the date to format, provided either as string, Number or Luxon object. If a string 
+   * is provided, that string needs to be parsable by Luxon
+   * @param {string} dateTimeFormat - the Luxon datetime format, defaults to dd/MM/yy T
    * @returns {String} the formatted string or null, if the provided date string or object is not valid or cannot be
    * parsed.
    */
   formatDateTime: function formatDateTime(date) {
-    return this.formatDate(date, DATE_TIME_FORMAT);
+    var dateTimeFormat = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : DATE_TIME_FORMAT;
+    return this.formatDate(date, dateTimeFormat);
   },
 
   /**
@@ -193,13 +229,13 @@ var util = {
   },
 
   /**
-   * Applies an offset to a unix timestamp to allow native JS dates and moment to render the resulting date in the
+   * Applies an offset to a unix timestamp to allow native JS dates and Luxon to render the resulting date in the
    * server's timezone, rather than the browsers time zone. The idea is to convert all timestamps of a time series
    * received from a server in a different time into offset timestamps, which then allows to render the data as chart
    * or table using the server's time and not the users time.
    * @param {number} timestamp: the original timestamp in seconds since 1970
    * @param {number} serverOffsetMin: the number of minutes behind UTC (e.g. +10:00 is 600 minutes after UTC)
-   * @returns {number} the offset timestamp which when used by moment or as argument for new Date(..) will produce a
+   * @returns {number} the offset timestamp which when used by Luxon or as argument for new Date(..) will produce a
    * date / time string in the server's timezone rather than the users/browser timezone
    */
   applyTimeZoneOffset: function applyTimeZoneOffset(timestamp) {
@@ -430,9 +466,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 +498,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.
    */
@@ -533,19 +574,20 @@ var util = {
         return;
       }
 
-      return current[k];
+      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 
+   * 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,7 +618,63 @@ 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;
+var _default = qndUtils;
 exports["default"] = _default;

package/index.js

@@ -1 +1 @@
-module.exports = require("./dist/util").default
+module.exports = { util: require("./dist/functions").default }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quick-n-dirty-utils",
-  "version": "0.0.13",
+  "version": "1.0.0",
   "description": "Little useful nuggets for accelerated web development",
   "scripts": {
     "build": "./node_modules/.bin/babel src --out-dir ./dist",
@@ -22,7 +22,7 @@
   },
   "homepage": "https://github.com/ilfrich/quick-n-dirty-utils#readme",
   "dependencies": {
-    "moment": "^2.24.0"
+    "luxon": "^3.0.1"
   },
   "devDependencies": {
     "@babel/cli": "^7.2.2",