Merge c230bb9 into 1a7a080

.gitignore

@@ -1,3 +1,4 @@
 .nyc_output
+yarn-error.log
 node_modules
-dist
+dist

.jsdoc.json

@@ -0,0 +1,21 @@
+{
+  "source": {
+    "include": [
+      "src",
+      "package.json",
+      "README.md"
+    ],
+    "includePattern": ".js$",
+    "excludePattern": "(node_modules/|docs)"
+  },
+  "templates": {
+    "referenceTitle": "Geoblink Lodash Mixins",
+    "disableSort": true
+  },
+  "opts": {
+    "template": "./node_modules/jsdoc-template",
+    "destination": "./docs/",
+    "encoding": "utf8",
+    "recurse": true
+  }
+}

.npmignore

@@ -1,4 +1,4 @@
 .*
 docs
 test
-src
+src

README.md

@@ -1,7 +1,12 @@
+[![GitHub license](https://img.shields.io/github/license/geoblink/lodash-mixins.svg)](https://github.com/geoblink/lodash-mixins/blob/master/LICENSE)
 [![Build Status](https://travis-ci.org/geoblink/lodash-mixins.svg?branch=master)](https://travis-ci.org/geoblink/lodash-mixins)
 [![Coverage Status](https://coveralls.io/repos/github/geoblink/lodash-mixins/badge.svg)](https://coveralls.io/github/geoblink/lodash-mixins)
+![npm bundle size (minified)](https://img.shields.io/bundlephobia/min/@geoblink/lodash-mixins.svg)
+![npm](https://img.shields.io/npm/v/@geoblink/lodash-mixins.svg)
 
-# lodash-mixins
+
+
+# @geoblink/lodash-mixins
 
 A collection of functionalities to extend lodash library.
 

package.json

@@ -13,7 +13,10 @@
     "test:dist": "run-s build && es-check es5 dist/**/*.js",
     "coverage": "nyc report --reporter=text-lcov | coveralls",
     "build": "rm -rf dist && babel src --out-dir dist",
-    "prepublishOnly": "run-s test build"
+    "docs": "run-s docs:*",
+    "docs:build": "jsdoc --configure .jsdoc.json --verbose",
+    "docs:commit": "if [[ $(git status docs --porcelain) ]]; then git add docs && git commit -m \":memo: Update documentation\"; fi",
+    "prepublishOnly": "run-s test build docs"
   },
   "keywords": [
     "lodash",
@@ -34,6 +37,8 @@
     "eslint-plugin-node": "^7.0.1",
     "eslint-plugin-promise": "^4.0.1",
     "eslint-plugin-standard": "^4.0.0",
+    "jsdoc": "^3.5.5",
+    "jsdoc-template": "https://github.com/braintree/jsdoc-template",
     "mocha": "^5.2.0",
     "mocha-lcov-reporter": "^1.3.0",
     "npm-run-all": "^4.1.3",

src/constants.js

@@ -1,16 +1,15 @@
-/**
- * -1|0|1
- * @typedef {Number} SortingOrder
- */
-
 /**
  * Possible results when comparing two items.
  * @readonly
+ * @constant
  * @enum {SortingOrder}
  */
 var SORTING_ORDER = {
+  /** Any negative number */
   LHS_BEFORE_RHS: -1,
+  /** Any positive number */
   LHS_AFTER_RHS: 1,
+  /** Zero */
   EQUAL: 0
 }
 

src/fromPairsMap.js

@@ -1,12 +1,15 @@
 var _ = require('lodash')
 
+module.exports = fromPairsMap
+
 /**
- * Applies fromPairs to the result of mapping the given iteratee to the given array.
+ * Applies `fromPairs` to the result of mapping given `iteratee` to given
+ * collection.
  *
- * @param {Array|Object} collection The collection to iterate over.
- * @param {Function} iteratee The function invoked per iteration.
- * @returns {Object} Returns the new object.
+ * @param {Array|Object} collection Collection to iterate over
+ * @param {Function} iteratee Function invoked per iteration
+ * @returns {Object} New object
  */
-module.exports = function fromPairsMap (collection, iteratee) {
+function fromPairsMap (collection, iteratee) {
   return _.fromPairs(_.map(collection, iteratee))
 }

src/getTruthyKeys.js

@@ -1,17 +1,22 @@
 var _ = require('lodash')
 
+module.exports = getTruthyKeys
+
 /**
- * Gets the truthy values of the collection.
+ * Gets the keys associated with truthy values in given collection.
  *
- * @param {Array|Object} collection The collection to iterate over.
- * @param {Function} parseKeyFunction The function invoked per iteration.
- * @returns {Object} Returns the new filtered collection.
+ * @param {Array|Object} collection Collection to iterate over.
+ * @param {Function} parseKeyFunction Function invoked per iteration. This
+ * function takes as parameter a key of a truthy value. The value it returns
+ * will be used in resulting list. Note that if this function returns a falsy
+ * value value, the key won't be present in resulting collection.
+ * @returns {Array} New list with just the keys of truthy entries, for which
+ * `parseKeyFunction` returned a truthy value.
  */
-module.exports = function getTruthyKeys (collection, parseKeyFunction) {
+function getTruthyKeys (collection, parseKeyFunction) {
   var isFunction = _.isFunction(parseKeyFunction)
   return _.filter(_.map(collection, function (value, key) {
-    if (value) {
-      return isFunction ? parseKeyFunction(key) : key
-    }
+    if (!value) return false
+    return isFunction ? parseKeyFunction(key) : key
   }))
 }

src/hasTruthyValues.js

@@ -1,13 +1,19 @@
 var shortcuttedReduce = require('./shortcuttedReduce')
 
+module.exports = hasTruthyValues
+
 /**
- * Returns whether given object has at least one truthy value for one of its keys.
+ * Returns whether given collection has at least one truthy value for one of its
+ * keys.
+ *
+ * This function stops traversing the collection as soon as it finds a truthy
+ * value.
  *
- * @param {Object} object Object to be checked.
+ * @param {Object|Array} collection Collection to iterate over.
  * @returns {Boolean} `true` if there's at least one value which is truthy.
  */
-module.exports = function hasTruthyValues (object) {
-  return shortcuttedReduce(object, function (accum, value) {
+function hasTruthyValues (collection) {
+  return shortcuttedReduce(collection, function (accum, value) {
     return accum || !!value
   })
 }

src/mGet.js

@@ -1,13 +1,20 @@
 var _ = require('lodash')
 
+module.exports = mGet
+
 /**
- * Multiple get.
+ * Returns multiple values of an object, defaulting missing ones to a common
+ * default.
  *
- * @param {Object} object The object to query.
- * @param {Array} arrayOfKeys Array with the paths of the properties to get.
- * @param {*} defaultValue The value returned for undefined resolved values.
- * @return {Array} Returns the new mapped array.
+ * @param {Object} object Object to be queried.
+ * @param {string[]} arrayOfKeys Array with the paths of the properties to get.
+ * @param {any} defaultValue The value returned for missing resolved values.
+ * @return {Array} New array with values for given key paths or default one.
  */
-module.exports = function mGet (object, arrayOfKeys, defaultValue) {
-  return _.map(arrayOfKeys, function (key) { return _.get(object, key, defaultValue) })
+function mGet (object, arrayOfKeys, defaultValue) {
+  return _.map(arrayOfKeys, getValueOrDefault)
+
+  function getValueOrDefault (key) {
+    return _.get(object, key, defaultValue)
+  }
 }

src/mapNonNil.js

@@ -1,13 +1,15 @@
 var _ = require('lodash')
 
+module.exports = mapNonNil
+
 /**
- * Map returning only non-nil elements
+ * Map function returning only non-nil elements.
  *
- * @param {Array|Object} collection The collection to iterate over.
- * @param {Function} iteratee The function invoked per iteration.
- * @returns {Array} Returns the new mapped array.
+ * @param {Array|Object} collection Collection to iterate over.
+ * @param {Function} iteratee Function invoked per iteration.
+ * @returns {Array} New mapped array.
  */
-module.exports = function mapNonNil (collection, iteratee) {
+function mapNonNil (collection, iteratee) {
   return _.filter(_.map(collection, iteratee), isNotNil)
 
   function isNotNil (item) {

src/mergeForEach.js

@@ -1,6 +1,8 @@
 var _ = require('lodash')
 var { SORTING_ORDER } = require('./constants')
 
+module.exports = mergeForEach
+
 /**
  * @template I
  * @typedef {string|string[]|function(I): any} Iteratee
@@ -31,8 +33,8 @@ var { SORTING_ORDER } = require('./constants')
  *
  * @template LHSItem
  * @template RHSItem
- * @param {{[key: string]: LHSItem}|LHSItem[]} lhs A collection of elements.
- * @param {{[key: string]: RHSItem}|RHSItem[]} rhs A collection of elements.
+ * @param {Object|LHSItem[]} lhs A collection of elements.
+ * @param {Object|RHSItem[]} rhs A collection of elements.
  * @param {object} options Options for comparison.
  * @param {Iteratee<LHSItem>} options.lhsIteratee Iteratee used to get the
  * value used to sort `lhs`. Returned value will be used to sort the collection
@@ -56,7 +58,7 @@ var { SORTING_ORDER } = require('./constants')
  * equivalent to `<` operator. Will receive as 3rd and 4th parameters the
  * iteratees used to get sorting value for `lhs` and `rhs`.
  */
-module.exports = function mergeForEach (lhs, rhs, {
+function mergeForEach (lhs, rhs, {
   lhsIteratee = function (lhsItem) { return lhsItem },
   rhsIteratee = function (rhsItem) { return rhsItem },
   innerCallback = function () {},

src/shortcuttedReduce.js

@@ -1,14 +1,18 @@
 var _ = require('lodash')
 
+module.exports = shortcuttedReduce
+
 /**
- * Like _.reduce but as soon as accumulator changes it finishes execution.
+ * Reduce which finish as soon as accumulator changes.
  *
+ * @template T Boolean | Number | String
  * @param {Array|Object} collection Collection to be reduced.
- * @param {Function} iteratee Function that will be called in each iteration. It'll receive as params the value and the index.
- * @param {Boolean|Integer|String} Accumulator. Note that is **must** be a simple primitive.
- * @returns {*} Returns the accumulated value.
+ * @param {Function} iteratee Function that will be called in each iteration.
+ * It'll receive as parameters the accumulator, the value and the index.
+ * @param {T} accumulator Note that is **must** be a simple primitive.
+ * @returns {T} Accumulated value.
  */
-module.exports = function shortcuttedReduce (collection, iteratee, accumulator) {
+function shortcuttedReduce (collection, iteratee, accumulator) {
   if (_.isObject(accumulator)) {
     throw new Error('Only simple primitives (boolean, numbers, strings...) are allowed')
   }