quick-n-dirty-utils 0.0.15 → 1.0.1

package/README.md

@@ -6,6 +6,8 @@ Little useful nuggets for accelerated web development.
 npm install --save quick-n-dirty-utils 
 ```
 
+*IMPORTANT: PLEASE READ THE [MIGRATION NOTES](https://github.com/ilfrich/quick-n-dirty-utils/releases/tag/1.0.0) FOR VERSION 1.0.0+*
+
 **Table of Contents**
 
 1. [Functions](#functions)
@@ -23,7 +25,7 @@ npm install --save quick-n-dirty-utils
 
 ```javascript
 // import dependency
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 // call a function of it
 const range = util.range(1, 10)
@@ -31,18 +33,18 @@ 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:
 
 ```jsx harmony
 import React from "react"
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const reactComponent = props => (
     <div>
@@ -50,21 +52,21 @@ 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:
 
 ```jsx harmony
 import React from "react"
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const reactComponent = props => (
     <div>
@@ -76,8 +78,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.
@@ -90,7 +92,7 @@ determined by the browser. Example offsets:
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const serverTimestamp = 1580777394
 
@@ -109,7 +111,7 @@ Familiar to Python programmers, this will create a list of sequential numeric va
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 let range = util.range(1, 5)  // will produce [1, 2, 3, 4, 5]
 range = util.range(5, 1, -1) // will produce [5, 4, 3, 2, 1]
@@ -123,7 +125,7 @@ currently only works for `min < max`.
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 let percentage = util.normalise(3, 0, 20)  // returns 0.15 or 15%
 percentage = util.normalise(10, 0, 20)  // return 0.5 or 50%
@@ -135,10 +137,20 @@ This is just a short hand for summing up numeric values in an array.
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const list = [5, 3.5, 10]
-sum = util.sum(list)  // returns 18.5
+const sum = util.sum(list)  // returns 18.5
+```
+
+#### `mean(list)`
+This is just a short hand for summing up numeric values in an array and dividing by its length.
+
+Example
+```javascript
+import { util } from "quick-n-dirty-utils"
+const list = [3, 3, 6]
+const avg = util.mean(list)  // returns 4.0
 ```
 
 ### REST
@@ -149,7 +161,7 @@ Small helper to just provide the `Content-Type` and `Accept` header for a `fetch
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 fetch("http://myurl.com", {
     headers: util.getJsonHeader(),
@@ -167,7 +179,7 @@ authentication.
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 fetch("http://myurl.com", {
     // will use the localStorage.getItem("auth_token") as Authorization header value; provide a custom key if required
@@ -185,7 +197,7 @@ requires authentication.
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 fetch("http://myurl.com", {
     // will use the localStorage.getItem("my_token") as Authorization header value; provide a custom key if required
@@ -204,7 +216,7 @@ status code and the response body as payload.
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 fetch("http://myurl.com", {
     headers: util.getAuthJsonHeader(),
@@ -226,7 +238,7 @@ When a React component uses a state variable to store a list of items any create
  following 2 functions are available:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 import React from "react"
 
 class MyComp extends React.Component {
@@ -271,7 +283,7 @@ Simple access wrapper for the browser's `localStorage` to store a login token. T
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 fetch("http://myurl.com/login", {
     method: "POST",
@@ -291,7 +303,7 @@ Counterpart to `setAuthToken(token, localStorageKey)`. This one deletes the key
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 fetch("http://myurl.com/logout", {
     method: "POST",
@@ -318,7 +330,7 @@ Redux, this will be useful. Using these helpers will avoid typos and thus improv
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const reduxAction = () => ({
     type: "myAction",
@@ -366,7 +378,7 @@ And then when the response of that request comes in either `_rejected` or `_fulf
 Some smaller helpers for handling colour gradients.
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 util.getTricolor(0.5)  // returns white
 util.getTricolor(0.7)  // returns pale blue
@@ -437,7 +449,7 @@ Updates a React component state's sorting definition. If the current `sortKey` i
 **Usage**
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 ...
 // initial state
@@ -467,7 +479,7 @@ Helper function that returns an `(a, b) => ...` lambda that can be used to sort
 **Usage**
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 ...
 // initial state, set in the constructor of the react component
 this.state = {
@@ -526,7 +538,7 @@ This function will extract a URL query part (the part after the `?`) and extract
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const queryString = "?id=abc&page=5"
 const query = util.getQueryStringParams(queryString)  // returns { id: "abc", page: "5" }
@@ -540,7 +552,7 @@ This functions creates a reverse mapping for a flat JSON object mapping from key
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const MAPPINMG = {
     key: "value1",
@@ -562,7 +574,7 @@ This function will first call `reverseMapping` on the input JSON object and then
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const MAPPING = {
     INVEST: "Investment and Portfolio",
@@ -580,7 +592,7 @@ This simple function has the purpose to access nested JSON objects without
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const myObject = {
     foo: {
@@ -608,7 +620,7 @@ The result will be a JSON object. Underneath each key, it will store
 Example:
 
 ```javascript
-import util from "quick-n-dirty-utils"
+import { util } from "quick-n-dirty-utils"
 
 const myList = [
     { _id: "a", name: "foo", level: 1, order: 1 },
@@ -653,3 +665,56 @@ const result3 = util.mapListToKeyObject(myList, item => item[level] + item[order
  * }
  */
 ```
+
+#### `getLast(array, defaultValue = null)`
+
+Retrieves the last element of an array or the provided `defaultValue`, in 
+ case the provided array is not an array or empty.
+
+```javascript
+import { util } from "quick-n-dirty-utils"
+
+const list = [0, 1, 2, 3, 4]
+console.log(getLast(list))  // will return 4
+```
+
+
+#### `arrayMatch(values, matchAgainst, minMatch = 1)`
+
+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.
+
+```javascript
+import { util } from "quick-n-dirty-utils"
+
+const items = [
+    { name: "Hello", tags: ["a"] },
+    { name: "World", tags: ["c"] },
+    { name: "Hello World", tags: ["a", "b"] },
+]
+let selectedTags = ["a", "b"]
+
+const active = items.filter(i => util.arrayMatch(i.tags, selectedTags))
+/* 
+ * will return:
+ * [{ name: "Hello", tags: ["a"] }, { name: "Hello World", tags: ["a", "b"] }]
+ */
+const twoActive = items.filter(i => util.arrayMatch(i.tags, selectedTags, 2))
+/* will return:
+ * [{ name: "Hello World", tags: ["a", "b"] }]
+ */
+```
+
+#### `arraySearch(values, filterFunction)`
+
+Finds the first match in a list of values that pass the `filterFunction` or `null` if no item in the list matches the
+function.
+
+```javascript
+import { util } from "quick-n-dirty-utils"
+
+const items = [0, 1, 2]
+const result1 = util.arraySearch(items, val => val === 2)  // returns 2
+const result2 = util.arraySearch(items, val => val === 3)  // returns null
+const result3 = util.arraySearch(items, val => val > 0)  // returns 1 (first match)
+```

package/dist/{util.js → functions.js}

@@ -5,9 +5,15 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports["default"] = void 0;
 
-var _moment = _interopRequireDefault(require("moment"));
+var _luxon = require("luxon");
 
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _nonIterableSpread(); }
+
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance"); }
+
+function _iterableToArray(iter) { if (Symbol.iterator in Object(iter) || Object.prototype.toString.call(iter) === "[object Arguments]") return Array.from(iter); }
+
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = new Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } }
 
 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 +32,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 +45,7 @@ var SORT_DIRECTIONS = {
  * Utilities used across components
  */
 
-var util = {
+var qndUtils = {
   /**
    * Default date format for quick display
    */
@@ -61,18 +67,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 +122,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 +237,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) {
@@ -443,6 +487,19 @@ var util = {
     }, 0);
   },
 
+  /**
+   * Provides the mean value of the provided list
+   * @param {Array} list - a list of numbers
+   * @returns {Number} the average value of the values in the list
+   */
+  mean: function mean(list) {
+    if (list.length === 0) {
+      return 0;
+    }
+
+    return this.sum(list) / list.length;
+  },
+
   /**
    * Extracts the query parameter of an URL query string and returns them as JSON object.
    * @param {string} query - the query string starting with ?, like ?foo=bar&abc=def
@@ -584,6 +641,56 @@ var util = {
     return result;
   },
 
+  /**
+   * Retrieves the last element of an array of the defaultValue, if the array is empty or not an array.
+   * @param {Array} array - an array of items
+   * @param {Object} defaultValue - the default value that will be returned if the provided array is empty or not an array.
+   * @returns {Object} the last element of the provided array or the default value
+   */
+  getLast: function getLast(array) {
+    var defaultValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
+
+    if (array == null || !Array.isArray(array) || array.length === 0) {
+      return defaultValue;
+    }
+
+    return array[array.length - 1];
+  },
+
+  /**
+   * 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, 
+   * 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.
+   */
+  arrayMatch: function arrayMatch() {
+    var values = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+    var matchAgainst = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+    var minMatch = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 1;
+    return values.filter(function (val) {
+      return matchAgainst.includes(val);
+    }).length >= minMatch;
+  },
+
+  /**
+   * Will return the first element of an array that matches the provided filter function. If no element matches, null
+   * will be returned.
+   * @param {Array} array - an array of items
+   * @param {function} filterFunction - a function that will be applied to each item in the array.
+   * @returns {Object} the first element of the array that matches the filter function or null, if no element matches.
+   */
+  arraySearch: function arraySearch(array, filterFunction) {
+    var filtered = array.filter(filterFunction);
+
+    if (filtered.length === 0) {
+      return null;
+    }
+
+    return filtered[0];
+  },
+
   /**
    * 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
@@ -638,7 +745,17 @@ var util = {
     }
 
     return "rgb(".concat(r, ", ").concat(g, ", ").concat(b, ")");
+  },
+
+  /**
+   * 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));
   }
 };
-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.15",
+  "version": "1.0.1",
   "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",