Lo-Dash ^v1.3.1

A low-level utility library delivering consistency, customization, performance, and extra features.

Download

• Lo-Dash builds (for modern environments):
  Development and Production

• Lo-Dash compatibility builds (for legacy and modern environments):
  Development and Production

• Underscore compatibility builds:
  Development and Production

• CDN copies of ≤ v1.3.1’s builds are available on cdnjs thanks to CloudFlare:
  Lo-Dash dev, Lo-Dash prod,
  Lo-Dash compat-dev, Lo-Dash compat-prod,
  Underscore compat-dev, and Underscore compat-prod

• For optimal file size, create a custom build with only the features you need

Dive in

We’ve got API docs, benchmarks, and unit tests.

For a list of upcoming features, check out our roadmap.

Resources

For more information check out these articles, screencasts, and other videos over Lo-Dash:

• Posts

• Say “Hello” to Lo-Dash

• Videos

• Introducing Lo-Dash
• Lo-Dash optimizations and custom builds
• Lo-Dash’s origin and why it’s a better utility belt
• Unit testing in Lo-Dash
• Lo-Dash’s approach to native method use
• CascadiaJS: Lo-Dash for a better utility belt

Features

• AMD loader support (RequireJS, curl.js, etc.)
• _(…) supports intuitive chaining
• _.at for cherry-picking collection values
• _.bindKey for binding “lazy” defined methods
• _.cloneDeep for deep cloning arrays and objects
• _.contains accepts a fromIndex argument
• _.debounce and _.throttle accept an options argument for more control
• _.createCallback to customize how callback arguments are handled and support callback shorthands in mixins
• _.findIndex and _.findKey for finding indexes and keys of collections
• _.forEach is chainable and supports exiting iteration early
• _.forIn for iterating over an object’s own and inherited properties
• _.forOwn for iterating over an object’s own properties
• _.isPlainObject checks if values are created by the Object constructor
• _.merge for a deep _.extend
• _.parseInt for consistent cross-environment behavior
• _.partial and _.partialRight for partial application without this binding
• _.runInContext for easier mocking and extended environment support
• _.support to flag environment features
• _.template supports “imports” options, ES6 template delimiters, and sourceURLs
• _.transform as a powerful alternative to _.reduce for transforming objects
• _.unzip as the inverse of _.zip
• _.where supports deep object comparisons
• _.clone, _.omit, _.pick, and more… accept callback and thisArg arguments
• _.contains, _.size, _.toArray, and more… accept strings
• _.filter, _.find, _.map, and more… support “_.pluck” and “_.where” callback shorthands

Support

Lo-Dash has been tested in at least Chrome 527, Firefox 221, IE 6-10, Opera 9.25~12, Safari 3-6, Node.js 0.4.8-0.10.7*, Narwhal 0.3.2, PhantomJS 1.9.0, RingoJS 0.9, and Rhino 1.7RC5.

* Node bugs #5622 and #5688 prevent the lodash command-line utility from creating minified builds in Node.js 0.10.8-0.10.11

Custom builds

Custom builds make it easy to create lightweight versions of Lo-Dash containing only the methods you need. To top it off, we handle all method dependency and alias mapping for you. For a more detailed summary over the differences between various builds, check out the wiki page.

• Backbone builds, with only methods required by Backbone, may be created using the backbone modifier argument.

lodash backbone

• Legacy builds, tailored for older environments without ES5 support, may be created using the legacy modifier argument.

lodash legacy

• Modern builds, tailored for newer environments with ES5 support, may be created using the modern modifier argument.

lodash modern

• Mobile builds, without method compilation and most bug fixes for old browsers, may be created using the mobile modifier argument.

lodash mobile

• Strict builds, with _.bindAll, _.defaults, and _.extend in strict mode, may be created using the strict modifier argument.

lodash strict

• Underscore builds, tailored for projects already using Underscore, may be created using the underscore modifier argument.

lodash underscore

Custom builds may be created using the following commands:

• Use the category argument to pass comma separated categories of methods to include in the build.
  Valid categories (case-insensitive) are “arrays”, “chaining”, “collections”, “functions”, “objects”, and “utilities”.

lodash category=collections,functions
lodash category="collections, functions"

• Use the exports argument to pass comma separated names of ways to export the LoDash function.
  Valid exports are “amd”, “commonjs”, “global”, “node”, and “none”.

lodash exports=amd,commonjs,node
lodash exports="amd, commonjs, node"

• Use the iife argument to specify code to replace the immediately-invoked function expression that wraps Lo-Dash.

lodash iife="!function(window,undefined){%output%}(this)"

• Use the include argument to pass comma separated method/category names to include in the build.

lodash include=each,filter,map
lodash include="each, filter, map"

• Use the minus argument to pass comma separated method/category names to remove from those included in the build.

lodash underscore minus=result,shuffle
lodash underscore minus="result, shuffle"

• Use the plus argument to pass comma separated method/category names to add to those included in the build.

lodash backbone plus=random,template
lodash backbone plus="random, template"

• Use the template argument to pass the file path pattern used to match template files to precompile.

lodash template="./*.jst"

• Use the settings argument to pass the template settings used when precompiling templates.

lodash settings="{interpolate:/\{\{([\s\S]+?)\}\}/g}"

• Use the moduleId argument to specify the AMD module ID of Lo-Dash, which defaults to “lodash”, used by precompiled templates.

lodash moduleId="underscore"

All arguments, except legacy with mobile, modern, or underscore, may be combined.
Unless specified by -o or --output, all files created are saved to the current working directory.

The following options are also supported:

• -c, --stdout ......... Write output to standard output
• -d, --debug ........... Write only the non-minified development output
• -h, --help ............. Display help information
• -m, --minify ......... Write only the minified production output
• -o, --output ......... Write output to a given path/filename
• -p, --source-map .. Generate a source map for the minified output, using an optional source map URL
• -s, --silent ......... Skip status updates normally logged to the console
• -V, --version ....... Output current version of Lo-Dash

The lodash command-line utility is available when Lo-Dash is installed as a global package (i.e. npm install -g lodash).

Installation and usage

In browsers:

<script src="lodash.js"></script>

Using npm:

npm install lodash

npm install -g lodash
npm link lodash

To avoid potential issues, update npm before installing Lo-Dash:

npm install npm -g

In Node.js and RingoJS ≥ v0.8.0:

var _ = require('lodash');

// or as a drop-in replacement for Underscore
var _ = require('lodash/dist/lodash.underscore');

Note: If Lo-Dash is installed globally, run npm link lodash in your project’s root directory before requiring it.

In RingoJS ≤ v0.7.0:

var _ = require('lodash')._;

In Rhino:

load('lodash.js');

In an AMD loader like RequireJS:

require({
  'paths': {
    'underscore': 'path/to/lodash'
  }
},
['underscore'], function(_) {
  console.log(_.VERSION);
});

Release Notes

^v1.3.1

• Added missing cache property to the objects returned by getObject
• Ensured maxWait unit tests pass in Ringo
• Increased the maxPoolSize value
• Optimized releaseArray and releaseObject

^v1.3.0

• Added _.transform method
• Added _.chain and _.findWhere aliases
• Added internal array and object pooling
• Added Istanbul test coverage reports to Travis CI
• Added maxWait option to _.debounce
• Added support for floating point numbers to _.random
• Added Volo configuration to package.json
• Adjusted UMD for component build
• Allowed more stable mixing of lodash and underscore build methods
• Ensured debounced function with, leading and trailing options, works as expected
• Ensured minified builds work with the Dojo builder
• Ensured minification avoids deoptimizing expressions containing boolean values
• Ensured support for --output paths containing build command keywords
• Ensured unknown types return false in _.isObject and _.isRegExp
• Ensured _.clone, _.flatten, and _.uniq can be used as a callback for methods like _.map
• Ensured _.forIn works on objects with longer inheritance chains in IE < 9
• Ensured _.isPlainObject returns true for empty objects in IE < 9
• Ensured _.max and _.min chain correctly
• Ensured clearTimeout use doesn’t cause errors in Titanium
• Ensured that the --stdout build option doesn't write to a file
• Exposed memoized function’s cache
• Fixed Error.prototype iteration bugs
• Fixed "scripts" paths in component.json
• Made methods support customizing _.indexOf
• Made the build track dependencies of private functions
• Made the template pre-compiler build option avoid escaping non-ascii characters
• Made _.createCallback avoid binding functions if they don’t reference this
• Optimized the Closure Compiler minification process
• Optimized the large array cache for _.difference, _.intersection, and _.uniq
• Optimized internal _.flatten and _.indexOf use
• Reduced _.unzip and _.zip
• Removed special handling of arrays in _.assign and _.defaults

The full changelog is available here.

BestieJS

Lo-Dash is part of the BestieJS “Best in Class” module collection. This means we promote solid browser/environment support, ES5+ precedents, unit testing, and plenty of documentation.

Author

John-David Dalton

Contributors

Kit Cambridge	Mathias Bynens