wrapperLodash.js 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148
  1. var LazyWrapper = require('./_LazyWrapper'),
  2. LodashWrapper = require('./_LodashWrapper'),
  3. baseLodash = require('./_baseLodash'),
  4. isArray = require('./isArray'),
  5. isObjectLike = require('./isObjectLike'),
  6. wrapperClone = require('./_wrapperClone');
  7. /** Used for built-in method references. */
  8. var objectProto = Object.prototype;
  9. /** Used to check objects for own properties. */
  10. var hasOwnProperty = objectProto.hasOwnProperty;
  11. /**
  12. * Creates a `lodash` object which wraps `value` to enable implicit method
  13. * chain sequences. Methods that operate on and return arrays, collections,
  14. * and functions can be chained together. Methods that retrieve a single value
  15. * or may return a primitive value will automatically end the chain sequence
  16. * and return the unwrapped value. Otherwise, the value must be unwrapped
  17. * with `_#value`.
  18. *
  19. * Explicit chain sequences, which must be unwrapped with `_#value`, may be
  20. * enabled using `_.chain`.
  21. *
  22. * The execution of chained methods is lazy, that is, it's deferred until
  23. * `_#value` is implicitly or explicitly called.
  24. *
  25. * Lazy evaluation allows several methods to support shortcut fusion.
  26. * Shortcut fusion is an optimization to merge iteratee calls; this avoids
  27. * the creation of intermediate arrays and can greatly reduce the number of
  28. * iteratee executions. Sections of a chain sequence qualify for shortcut
  29. * fusion if the section is applied to an array and iteratees accept only
  30. * one argument. The heuristic for whether a section qualifies for shortcut
  31. * fusion is subject to change.
  32. *
  33. * Chaining is supported in custom builds as long as the `_#value` method is
  34. * directly or indirectly included in the build.
  35. *
  36. * In addition to lodash methods, wrappers have `Array` and `String` methods.
  37. *
  38. * The wrapper `Array` methods are:
  39. * `concat`, `join`, `pop`, `push`, `shift`, `sort`, `splice`, and `unshift`
  40. *
  41. * The wrapper `String` methods are:
  42. * `replace` and `split`
  43. *
  44. * The wrapper methods that support shortcut fusion are:
  45. * `at`, `compact`, `drop`, `dropRight`, `dropWhile`, `filter`, `find`,
  46. * `findLast`, `head`, `initial`, `last`, `map`, `reject`, `reverse`, `slice`,
  47. * `tail`, `take`, `takeRight`, `takeRightWhile`, `takeWhile`, and `toArray`
  48. *
  49. * The chainable wrapper methods are:
  50. * `after`, `ary`, `assign`, `assignIn`, `assignInWith`, `assignWith`, `at`,
  51. * `before`, `bind`, `bindAll`, `bindKey`, `castArray`, `chain`, `chunk`,
  52. * `commit`, `compact`, `concat`, `conforms`, `constant`, `countBy`, `create`,
  53. * `curry`, `debounce`, `defaults`, `defaultsDeep`, `defer`, `delay`,
  54. * `difference`, `differenceBy`, `differenceWith`, `drop`, `dropRight`,
  55. * `dropRightWhile`, `dropWhile`, `extend`, `extendWith`, `fill`, `filter`,
  56. * `flatMap`, `flatMapDeep`, `flatMapDepth`, `flatten`, `flattenDeep`,
  57. * `flattenDepth`, `flip`, `flow`, `flowRight`, `fromPairs`, `functions`,
  58. * `functionsIn`, `groupBy`, `initial`, `intersection`, `intersectionBy`,
  59. * `intersectionWith`, `invert`, `invertBy`, `invokeMap`, `iteratee`, `keyBy`,
  60. * `keys`, `keysIn`, `map`, `mapKeys`, `mapValues`, `matches`, `matchesProperty`,
  61. * `memoize`, `merge`, `mergeWith`, `method`, `methodOf`, `mixin`, `negate`,
  62. * `nthArg`, `omit`, `omitBy`, `once`, `orderBy`, `over`, `overArgs`,
  63. * `overEvery`, `overSome`, `partial`, `partialRight`, `partition`, `pick`,
  64. * `pickBy`, `plant`, `property`, `propertyOf`, `pull`, `pullAll`, `pullAllBy`,
  65. * `pullAllWith`, `pullAt`, `push`, `range`, `rangeRight`, `rearg`, `reject`,
  66. * `remove`, `rest`, `reverse`, `sampleSize`, `set`, `setWith`, `shuffle`,
  67. * `slice`, `sort`, `sortBy`, `splice`, `spread`, `tail`, `take`, `takeRight`,
  68. * `takeRightWhile`, `takeWhile`, `tap`, `throttle`, `thru`, `toArray`,
  69. * `toPairs`, `toPairsIn`, `toPath`, `toPlainObject`, `transform`, `unary`,
  70. * `union`, `unionBy`, `unionWith`, `uniq`, `uniqBy`, `uniqWith`, `unset`,
  71. * `unshift`, `unzip`, `unzipWith`, `update`, `updateWith`, `values`,
  72. * `valuesIn`, `without`, `wrap`, `xor`, `xorBy`, `xorWith`, `zip`,
  73. * `zipObject`, `zipObjectDeep`, and `zipWith`
  74. *
  75. * The wrapper methods that are **not** chainable by default are:
  76. * `add`, `attempt`, `camelCase`, `capitalize`, `ceil`, `clamp`, `clone`,
  77. * `cloneDeep`, `cloneDeepWith`, `cloneWith`, `conformsTo`, `deburr`,
  78. * `defaultTo`, `divide`, `each`, `eachRight`, `endsWith`, `eq`, `escape`,
  79. * `escapeRegExp`, `every`, `find`, `findIndex`, `findKey`, `findLast`,
  80. * `findLastIndex`, `findLastKey`, `first`, `floor`, `forEach`, `forEachRight`,
  81. * `forIn`, `forInRight`, `forOwn`, `forOwnRight`, `get`, `gt`, `gte`, `has`,
  82. * `hasIn`, `head`, `identity`, `includes`, `indexOf`, `inRange`, `invoke`,
  83. * `isArguments`, `isArray`, `isArrayBuffer`, `isArrayLike`, `isArrayLikeObject`,
  84. * `isBoolean`, `isBuffer`, `isDate`, `isElement`, `isEmpty`, `isEqual`,
  85. * `isEqualWith`, `isError`, `isFinite`, `isFunction`, `isInteger`, `isLength`,
  86. * `isMap`, `isMatch`, `isMatchWith`, `isNaN`, `isNative`, `isNil`, `isNull`,
  87. * `isNumber`, `isObject`, `isObjectLike`, `isPlainObject`, `isRegExp`,
  88. * `isSafeInteger`, `isSet`, `isString`, `isUndefined`, `isTypedArray`,
  89. * `isWeakMap`, `isWeakSet`, `join`, `kebabCase`, `last`, `lastIndexOf`,
  90. * `lowerCase`, `lowerFirst`, `lt`, `lte`, `max`, `maxBy`, `mean`, `meanBy`,
  91. * `min`, `minBy`, `multiply`, `noConflict`, `noop`, `now`, `nth`, `pad`,
  92. * `padEnd`, `padStart`, `parseInt`, `pop`, `random`, `reduce`, `reduceRight`,
  93. * `repeat`, `result`, `round`, `runInContext`, `sample`, `shift`, `size`,
  94. * `snakeCase`, `some`, `sortedIndex`, `sortedIndexBy`, `sortedLastIndex`,
  95. * `sortedLastIndexBy`, `startCase`, `startsWith`, `stubArray`, `stubFalse`,
  96. * `stubObject`, `stubString`, `stubTrue`, `subtract`, `sum`, `sumBy`,
  97. * `template`, `times`, `toFinite`, `toInteger`, `toJSON`, `toLength`,
  98. * `toLower`, `toNumber`, `toSafeInteger`, `toString`, `toUpper`, `trim`,
  99. * `trimEnd`, `trimStart`, `truncate`, `unescape`, `uniqueId`, `upperCase`,
  100. * `upperFirst`, `value`, and `words`
  101. *
  102. * @name _
  103. * @constructor
  104. * @category Seq
  105. * @param {*} value The value to wrap in a `lodash` instance.
  106. * @returns {Object} Returns the new `lodash` wrapper instance.
  107. * @example
  108. *
  109. * function square(n) {
  110. * return n * n;
  111. * }
  112. *
  113. * var wrapped = _([1, 2, 3]);
  114. *
  115. * // Returns an unwrapped value.
  116. * wrapped.reduce(_.add);
  117. * // => 6
  118. *
  119. * // Returns a wrapped value.
  120. * var squares = wrapped.map(square);
  121. *
  122. * _.isArray(squares);
  123. * // => false
  124. *
  125. * _.isArray(squares.value());
  126. * // => true
  127. */
  128. function lodash(value) {
  129. if (isObjectLike(value) && !isArray(value) && !(value instanceof LazyWrapper)) {
  130. if (value instanceof LodashWrapper) {
  131. return value;
  132. }
  133. if (hasOwnProperty.call(value, '__wrapped__')) {
  134. return wrapperClone(value);
  135. }
  136. }
  137. return new LodashWrapper(value);
  138. }
  139. // Ensure wrappers are instances of `baseLodash`.
  140. lodash.prototype = baseLodash.prototype;
  141. lodash.prototype.constructor = lodash;
  142. module.exports = lodash;