_(value)

Creates a lodash object which wraps value to enable implicit method chain sequences. Methods that operate on and return arrays, collections, and functions can be chained together. Methods that retrieve a single value or may return a primitive value will automatically end the chain sequence and return the unwrapped value. Otherwise, the value must be unwrapped with _#value.

Explicit chain sequences, which must be unwrapped with _#value, may be enabled using _.chain.

The execution of chained methods is lazy, that is, it’s deferred until _#value is implicitly or explicitly called.

Lazy evaluation allows several methods to support shortcut fusion. Shortcut fusion is an optimization to merge iteratee calls; this avoids the creation of intermediate arrays and can greatly reduce the number of iteratee executions. Sections of a chain sequence qualify for shortcut fusion if the section is applied to an array and iteratees accept only one argument. The heuristic for whether a section qualifies for shortcut fusion is subject to change.

Chaining is supported in custom builds as long as the _#value method is directly or indirectly included in the build.

In addition to lodash methods, wrappers have Array and String methods.

The wrapper Array methods are:
concat, join, pop, push, shift, sort, splice, and unshift

The wrapper String methods are:
replace and split

The wrapper methods that support shortcut fusion are:
at, compact, drop, dropRight, dropWhile, filter, find, findLast, head, initial, last, map, reject, reverse, slice, tail, take, takeRight, takeRightWhile, takeWhile, and toArray

The chainable wrapper methods are:
after, ary, assign, assignIn, assignInWith, assignWith, at, before, bind, bindAll, bindKey, castArray, chain, chunk, commit, compact, concat, conforms, constant, countBy, create, curry, debounce, defaults, defaultsDeep, defer, delay, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, extend, extendWith, fill, filter, flatMap, flatMapDeep, flatMapDepth, flatten, flattenDeep, flattenDepth, flip, flow, flowRight, fromPairs, functions, functionsIn, groupBy, initial, intersection, intersectionBy, intersectionWith, invert, invertBy, invokeMap, iteratee, keyBy, keys, keysIn, map, mapKeys, mapValues, matches, matchesProperty, memoize, merge, mergeWith, method, methodOf, mixin, negate, nthArg, omit, omitBy, once, orderBy, over, overArgs, overEvery, overSome, partial, partialRight, partition, pick, pickBy, plant, property, propertyOf, pull, pullAll, pullAllBy, pullAllWith, pullAt, push, range, rangeRight, rearg, reject, remove, rest, reverse, sampleSize, set, setWith, shuffle, slice, sort, sortBy, splice, spread, tail, take, takeRight, takeRightWhile, takeWhile, tap, throttle, thru, toArray, toPairs, toPairsIn, toPath, toPlainObject, transform, unary, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unset, unshift, unzip, unzipWith, update, updateWith, values, valuesIn, without, wrap, xor, xorBy, xorWith, zip, zipObject, zipObjectDeep, and zipWith

The wrapper methods that are not chainable by default are:
add, attempt, camelCase, capitalize, ceil, clamp, clone, cloneDeep, cloneDeepWith, cloneWith, conformsTo, deburr, defaultTo, divide, each, eachRight, endsWith, eq, escape, escapeRegExp, every, find, findIndex, findKey, findLast, findLastIndex, findLastKey, first, floor, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, get, gt, gte, has, hasIn, head, identity, includes, indexOf, inRange, invoke, isArguments, isArray, isArrayBuffer, isArrayLike, isArrayLikeObject, isBoolean, isBuffer, isDate, isElement, isEmpty, isEqual, isEqualWith, isError, isFinite, isFunction, isInteger, isLength, isMap, isMatch, isMatchWith, isNaN, isNative, isNil, isNull, isNumber, isObject, isObjectLike, isPlainObject, isRegExp, isSafeInteger, isSet, isString, isUndefined, isTypedArray, isWeakMap, isWeakSet, join, kebabCase, last, lastIndexOf, lowerCase, lowerFirst, lt, lte, max, maxBy, mean, meanBy, min, minBy, multiply, noConflict, noop, now, nth, pad, padEnd, padStart, parseInt, pop, random, reduce, reduceRight, repeat, result, round, runInContext, sample, shift, size, snakeCase, some, sortedIndex, sortedIndexBy, sortedLastIndex, sortedLastIndexBy, startCase, startsWith, stubArray, stubFalse, stubObject, stubString, stubTrue, subtract, sum, sumBy, template, times, toFinite, toInteger, toJSON, toLength, toLower, toNumber, toSafeInteger, toString, toUpper, trim, trimEnd, trimStart, truncate, unescape, uniqueId, upperCase, upperFirst, value, and words

Arguments

  1. value (*): The value to wrap in a lodash instance.

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. function square(n) {
  2.   return n * n;
  3. }
  5. var wrapped = _([1, 2, 3]);
  7. // Returns an unwrapped value.
  8. wrapped.reduce(_.add);
  9. // => 6
  11. // Returns a wrapped value.
  12. var squares = wrapped.map(square);
  14. _.isArray(squares);
  15. // => false
  17. _.isArray(squares.value());
  18. // => true

_.chain(value)

Creates a lodash wrapper instance that wraps value with explicit method chain sequences enabled. The result of such sequences must be unwrapped with _#value.

Since

1.3.0

Arguments

  1. value (*): The value to wrap.

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. var users = [
  2.   { 'user': 'barney',  'age': 36 },
  3.   { 'user': 'fred',    'age': 40 },
  4.   { 'user': 'pebbles', 'age': 1 }
  5. ];
  7. var youngest = _
  8.   .chain(users)
  9.   .sortBy('age')
  10.   .map(function(o) {
  11.     return o.user + ' is ' + o.age;
  12.   })
  13.   .head()
  14.   .value();
  15. // => 'pebbles is 1'

_.tap(value, interceptor)

This method invokes interceptor and returns value. The interceptor is invoked with one argument; (value). The purpose of this method is to “tap into” a method chain sequence in order to modify intermediate results.

Since

0.1.0

Arguments

  1. value (*): The value to provide to interceptor.
  2. interceptor (Function): The function to invoke.

Returns

(*): Returns value.

Example

  1. _([1, 2, 3])
  2.  .tap(function(array) {
  3.    // Mutate input array.
  4.    array.pop();
  5.  })
  6.  .reverse()
  7.  .value();
  8. // => [2, 1]

_.thru(value, interceptor)

This method is like _.tap except that it returns the result of interceptor. The purpose of this method is to “pass thru” values replacing intermediate results in a method chain sequence.

Since

3.0.0

Arguments

  1. value (*): The value to provide to interceptor.
  2. interceptor (Function): The function to invoke.

Returns

(*): Returns the result of interceptor.

Example

  1. _('  abc  ')
  2.  .chain()
  3.  .trim()
  4.  .thru(function(value) {
  5.    return [value];
  6.  })
  7.  .value();
  8. // => ['abc']

_.prototype[Symbol.iterator]()

Enables the wrapper to be iterable.

Since

4.0.0

Returns

(Object): Returns the wrapper object.

Example

  1. var wrapped = _([1, 2]);
  3. wrapped[Symbol.iterator]() === wrapped;
  4. // => true
  6. Array.from(wrapped);
  7. // => [1, 2]

_.prototype.at([paths])

This method is the wrapper version of _.at.

Since

1.0.0

Arguments

  1. [paths] (…(string|string[])): The property paths to pick.

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. var object = { 'a': [{ 'b': { 'c': 3 } }, 4] };
  3. _(object).at(['a[0].b.c', 'a[1]']).value();
  4. // => [3, 4]

_.prototype.chain()

Creates a lodash wrapper instance with explicit method chain sequences enabled.

Since

0.1.0

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. var users = [
  2.   { 'user': 'barney', 'age': 36 },
  3.   { 'user': 'fred',   'age': 40 }
  4. ];
  6. // A sequence without explicit chaining.
  7. _(users).head();
  8. // => { 'user': 'barney', 'age': 36 }
  10. // A sequence with explicit chaining.
  11. _(users)
  12.   .chain()
  13.   .head()
  14.   .pick('user')
  15.   .value();
  16. // => { 'user': 'barney' }

_.prototype.commit()

Executes the chain sequence and returns the wrapped result.

Since

3.2.0

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. var array = [1, 2];
  2. var wrapped = _(array).push(3);
  4. console.log(array);
  5. // => [1, 2]
  7. wrapped = wrapped.commit();
  8. console.log(array);
  9. // => [1, 2, 3]
  11. wrapped.last();
  12. // => 3
  14. console.log(array);
  15. // => [1, 2, 3]

_.prototype.next()

Gets the next value on a wrapped object following the iterator protocol.

Since

4.0.0

Returns

(Object): Returns the next iterator value.

Example

  1. var wrapped = _([1, 2]);
  3. wrapped.next();
  4. // => { 'done': false, 'value': 1 }
  6. wrapped.next();
  7. // => { 'done': false, 'value': 2 }
  9. wrapped.next();
  10. // => { 'done': true, 'value': undefined }

_.prototype.plant(value)

Creates a clone of the chain sequence planting value as the wrapped value.

Since

3.2.0

Arguments

  1. value (*): The value to plant.

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. function square(n) {
  2.   return n * n;
  3. }
  5. var wrapped = _([1, 2]).map(square);
  6. var other = wrapped.plant([3, 4]);
  8. other.value();
  9. // => [9, 16]
  11. wrapped.value();
  12. // => [1, 4]

_.prototype.reverse()

This method is the wrapper version of _.reverse.

Note: This method mutates the wrapped array.

Since

0.1.0

Returns

(Object): Returns the new lodash wrapper instance.

Example

  1. var array = [1, 2, 3];
  3. _(array).reverse().value()
  4. // => [3, 2, 1]
  6. console.log(array);
  7. // => [3, 2, 1]

_.prototype.value()

Executes the chain sequence to resolve the unwrapped value.

Since

0.1.0

Aliases

.prototype.toJSON, .prototype.valueOf

Returns

(*): Returns the resolved unwrapped value.

Example

  1. _([1, 2, 3]).value();
  2. // => [1, 2, 3]