node package manager
Painless code sharing. npm Orgs help your team discover, share, and reuse code. Create a free org »

lodash-addons

Lodash Addons

Build Status Dependencies

A collection of utility mixins for lodash. Supports both CommonJS and AMD module formats (meaning, works well in node/webpack or RequireJS-based projects).

Installation

Node: npm install -save lodash-addons

Bower bower install --save lodash-addons

Array

Collection

Lang

Math

Object

Preconditions

String

Util

Methods

“Array” Methods

# _.changes(first, second)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L57 "View in source") [Ⓣ][1]

Gets indices for which elements differ between two arrays.

Arguments

  1. first (array): First array
  2. second (array): Second array

Example

_.changes([false, true], [false, false]);
// => [1] 

# _.exceptKeys(array, indices, iteratee)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L324 "View in source") [Ⓣ][1]

Iterate array skipping given indices.

Arguments

  1. array (array): Source array
  2. indices (array): Indices to skip
  3. iteratee (function): Iteratee

Example

_.exceptKeys(['a', 'b', 'c', 'd'], [1, 3], function(val) {
  // skips "b" and "d" 
});

# _.indexesOf(array, predicate)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L731 "View in source") [Ⓣ][1]

Gets indices for elements which predicate returns truthy for.

Arguments

  1. array (array): Target array
  2. predicate (function): Predicate value or function.

Example

_.indexesOf([3, false, 3], _.isNumber);
// => [0, 2] 
 
_.indexesOf([3, false, 3], 3);
// => [0, 2] 

“Collection” Methods

# _.mapFiltered(array, predicate, iteratee)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L790 "View in source") [Ⓣ][1]

Map a function to filtered array elements.

Arguments

  1. array (array): Array
  2. predicate (function): Validation method for each element.
  3. iteratee (function): Function to call on each valid element.

# _.recurse(collection, iteratee)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L900 "View in source") [Ⓣ][1]

Invoke a function recursively on every element in a collection.

Arguments

  1. collection (array|object): Collection
  2. iteratee (function): Function to invoke

“Lang” Methods

# _.getArray(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L405 "View in source") [Ⓣ][1]

Returns value if an array, otherwise a default.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getArray(null)
// => [] 
 
_.getArray(null, ['test'])
// => ['test'] 

# _.getBoolean(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L426 "View in source") [Ⓣ][1]

Returns value if a boolean, otherwise a default boolean.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getBoolean(null)
// => false 
 
_.getBoolean(null, true)
// => true 

# _.getFinite(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L450 "View in source") [Ⓣ][1]

Returns value if a finite number, otherwise a default number.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getFinite('')
// => 0 
 
_.getFinite('', 100)
// => 100 
 
_.getFinite(NaN, 25)
// => 25 

# _.getFunction(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L468 "View in source") [Ⓣ][1]

Returns value if a function, otherwise a default function.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getFunction(null)
// => function () {} 

# _.getMap(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L482 "View in source") [Ⓣ][1]

Returns value if a Map, otherwise a default map.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

# _.getNumber(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L521 "View in source") [Ⓣ][1]

Returns value if a number, otherwise a default number.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getNumber('')
// => 0 
 
_.getNumber('', 100)
// => 100 

# _.getObject(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L539 "View in source") [Ⓣ][1]

Returns value if a object, otherwise a default object.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getObject('')
// => {} 

# _.getPlainObject(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L500 "View in source") [Ⓣ][1]

Returns value if a plain object, otherwise a default object.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getPlainObject('')
// => {} 

# _.getSet(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L557 "View in source") [Ⓣ][1]

Returns value if a Set, otherwise a default set.

Arguments

  1. value (mixed): Source value
  2. replacement (set): Custom default if value is invalid type.

Example

_.getSet('')
// => Set() 

# _.getString(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L575 "View in source") [Ⓣ][1]

Returns value if a string, otherwise a default string.

Arguments

  1. value (mixed): Source value
  2. replacement (number): Custom default if value is invalid type.

Example

_.getString(false)
// => '' 

# _.getWeakMap(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L593 "View in source") [Ⓣ][1]

Returns value if a WeakMap, otherwise a default WeakMap.

Arguments

  1. value (mixed): Source value
  2. replacement (weakmap): Custom default if value is invalid type.

Example

_.getWeakMap(false)
// => '' 

# _.getWeakSet(value, replacement)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L611 "View in source") [Ⓣ][1]

Returns value if a WeakSet, otherwise a default WeakSet.

Arguments

  1. value (mixed): Source value
  2. replacement (weakset): Custom default if value is invalid type.

Example

_.getWeakSet(false)
// => '' 

# _.toBool(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L1015 "View in source") [Ⓣ][1]

Converts a value to a boolean.

Arguments

  1. value (*): Source value

Example

_.toBool(1)
// => true 

“Math” Methods

# _.sign(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L981 "View in source") [Ⓣ][1]

Indicates whether a numeric value is positive (returns 1) or negative (returns -1).

Arguments

  1. value (number): Numeric value.

Example

_.sign(40)
// => 1 
 
_.sign(-40)
// => -1 

“Object” Methods

# _.fromQueryString(string)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L352 "View in source") [Ⓣ][1]

Parses query string into key/value object.

Arguments

  1. string (string): Query string.

Example

_.fromQueryString('key=value');
// => { key: 'value' } 

# _.hasOfType(value, property, validator)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L659 "View in source") [Ⓣ][1]

If _.has returns true, run a validator on value.

Arguments

  1. value (mixed): Collection for _.has
  2. property (number|string): Propert/key name.
  3. validator (function): Function to validate value.

Example

_.hasOfType({ test: '' }, 'test', _.isString)
// => true 

# _.hasPrototypeOfType(value, property, predicate)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L680 "View in source") [Ⓣ][1]

Returns whether an object has a prototype property of the given type.

Arguments

  1. value (*): Source value.
  2. property (string): Prototype property.
  3. predicate (function): Validation function.

# _.immutable(object, key, value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L700 "View in source") [Ⓣ][1]

Creates an immutable property on an object.

Arguments

  1. object (object): Target object
  2. key (string): Property.
  3. value (mixed): Value.

# _.mixInto(target, source)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L804 "View in source") [Ⓣ][1]

Merge prototype properties from source to target.

Arguments

  1. target (function|object): Target object.
  2. source (function|object): Object/function to mixin.

# _.objectWith(object, path, value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L844 "View in source") [Ⓣ][1]

Shorthand object creation when sole property is a variable, or a path.

Arguments

  1. object (): Existing object *(optional)*
  2. path (number|string): Property
  3. value (mixed): Value

Example

// To create a new object: 
 
_.objectWith('key', 'value')
// => { key: 'value' } 
 
_.objectWith('a.deep.path', 'value')
// => { 
  a: {
    deep: {
    path: 'value'
    }
  }
}
 
// Using existing: 
_.objectWith({ a: 1 }, 'b', 2)
// => { a: 1, b: 2 } 

# _.omitDeep(object, keys)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L880 "View in source") [Ⓣ][1]

Run _.omit recursively down a collection.

Arguments

  1. object (array|object): Collection
  2. keys (array): Array of property/key names to omit

# _.requestSetter(object, property)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L930 "View in source") [Ⓣ][1]

Gives a setter for prop only to the first requesting caller.

Creates request[Prop]Setter and get[Prop] methods on the source object. The first caller to request[Prop]Setter gets it and therefore is the only one allowed to invoke it.

Any caller may use the getter.

Arguments

  1. object (object): Target object.
  2. property (string): Property name.

# _.toObject(object)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L1053 "View in source") [Ⓣ][1]

Recursively invokes "toObject" on objects which support the method.

Many complex objects from libraries like Collections.js, Mongoose, support to a toObject method for converting to plain objects.

Arguments

  1. object (object): Original object.

# _.toQueryString(object)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L1032 "View in source") [Ⓣ][1]

Converts an object's key/values to a query string.

Arguments

  1. object (object): Source key/value collection

Example

_.toQueryString({ a: 1, b: 2 })
// => a=1&b=2 

# _.validatedAssign(models, source, strict)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L1105 "View in source") [Ⓣ][1]

This method is like _.defaultsDeep except it recursively assigns default properties if the provided values do not exist OR do not match a given type.

Property value types are inferred from the default value. A default of "1" is a number, so any incoming value not of type "Number" are rejected.

To allow a default value which is a different type then the validation, you can define both a validator and default for each property.

Arguments

  1. models (object): Object of default properties and/or a schema for validation.
  2. source (object): Object to be validated and merged.
  3. strict (boolean): Only properties defined in the model allowed through

Example

_.validatedAssign({ id: 0 }, {});
// => { id: 0 } 
 
_.validatedAssign({ id: 0 }, { id: false });
// => { id: 0 } 
 
 
var model = {
  name: {
    validator: _.isNonEmptyString,
    default: false
  }
};
 
var incoming = {
  name: ''
};
 
_.validatedAssign(model, incoming);
// => { name: false } 

“Preconditions” Methods

# _.check(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L76 "View in source") [Ⓣ][1]

Throw a TypeError if value doesn't match one of any provided validation methods.

Arguments

  1. value (mixed): Value

# _.checkArray(array)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L107 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't an array.

Arguments

  1. array (mixed): Value

# _.checkBoolean(boolean)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L122 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a boolean.

Arguments

  1. boolean (mixed): Value

# _.checkCollection(collection)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L137 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't an array or object.

Arguments

  1. collection (mixed): Value

# _.checkFunction(func)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L152 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a function.

Arguments

  1. func (mixed): Value

# _.checkKey(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L167 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a number/string.

Arguments

  1. value (mixed): Value

# _.checkMap(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L182 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a Map.

Arguments

  1. value (mixed): Value

# _.checkNonEmpty(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L197 "View in source") [Ⓣ][1]

Throw a TypeError if value _.isEmpty

Arguments

  1. value (mixed): Value

# _.checkNumber(number)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L212 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a number.

Arguments

  1. number (mixed): Value

# _.checkObject(object)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L227 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't an object.

Arguments

  1. object (mixed): Value

# _.checkPlainObject(object)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L242 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a plain object.

Arguments

  1. object (mixed): Value

# _.checkSet(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L257 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a Set.

Arguments

  1. value (mixed): Value

# _.checkString(string)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L272 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a string.

Arguments

  1. string (mixed): Value

# _.checkWeakMap(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L287 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a WeakMap.

Arguments

  1. value (mixed): Value

# _.checkWeakSet(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L302 "View in source") [Ⓣ][1]

Throw a TypeError if value isn't a WeakSet.

Arguments

  1. value (mixed): Value

“String” Methods

# _.generateKey(n)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L376 "View in source") [Ⓣ][1]

Generates a random alphanumeric string with length n.

Arguments

  1. n (int): Desired length.

Example

_.generateKey(5)
// => 'L7IpD' 

# _.isNonEmptyString(string)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L775 "View in source") [Ⓣ][1]

Checks if value is a non-empty string.

Arguments

  1. string (object): String

Example

_.isNonEmptyString('')
// => false 

# _.slugify(string)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L998 "View in source") [Ⓣ][1]

Generates a url-safe "slug" form of a string.

Arguments

  1. string (string): String value.

Example

_.slugify('A Test')
// => a-test 

“Util” Methods

# _.getPrototype(value)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L628 "View in source") [Ⓣ][1]

Gets the prototype for the given value.

Arguments

  1. value (*): Source value

Example

_.getPrototype(5)
// => { toFixed: func(), ... } 

Methods

# isCollection(collection)

[Ⓢ](https://github.com/helion3/lodash-addons/blob/master/src/lodash-addons.js#L753 "View in source") [Ⓣ][1]

Checks if a value is either an array or an object.

Arguments

  1. collection (mixed): Value to check