lodash-decipher
A smattering of mixins for LoDash, by Decipher, Inc..
Install
$ bower install lodash-decipher
or
$ npm install lodash-decipher
Usage
AngularJS Goodies
This module distributes a separate set of file(s) that will mixin several more functions to LoDash that rely on AngularJS' API.
Is that a good idea? I don't know. Anyway...
If you want access to these functions, simply require decipher.lodash
from your main module, and it will mix itself into LoDash's _
object.
Note: These functions are not available during AngularJS' configuration phase, as they rely on services instead of providers.
In general, this will give you the extra functions:
angular;
Read on for specifics.
NodeJS
var _ = ; _; // [2, 3, 4]
lodash-decipher has a peer dependency upon LoDash, so if you install it, you get LoDash too. It exports the same object as returned by require('lodash')
.
NodeJS + AngularJS
If you have angular-node installed, the AngularJS Module
(decipher.lodash
) will automatically be registered when this module is required. Example:
var angular = _ = ; angular ;
Browser
For production usage:
LoDash must be loaded before lodash-decipher.
Browser + AngularJS
If you're using AngularJS, you may wish to use the lodash-decipher.ng*.js
files instead.
For production usage:
Note:
lodash-decipher.js
proper is included withinlodash-decipher.ng.js
.
Core API
Chainable Methods
_.transmogrify(value, func, [ignoreRx])
Walk an object depth-first and execute a function against each member, replacing the value of that member with the value returned by the function. Use _.applicator to generate a function which will call a function within each object member, if present. Will not walk functions.
Parameters
value: Object
, Object to walk.
func: Function
, Function to execute against each member.
ignoreRx: RegExp | string
, Any key matching this will not be walked.
Returns: *
, Transmogrified copy of your object.
Example:
// Given a deeply-nested object `foo`, return a deeply-nested object// wherein all members are converted to strings via their `toString()` methods.var bar = _; // Given a deeply-nested object `foo`, return a deeply-nested object// wherein all array members are converted to objects, ignoring// any arrays whose key contains `$`.var bar = _;
_.morph(value, [callback], [thisArg])
Convenience method. Calls _.map
or _.mapValues
as appropriate on value
. If value
is not an Array or Object, value
will be returned.
Parameters
value: Object | Array
, Value to map
or mapValues
against.
[callback]: Function | Object
, Function to execute, or _.pluck
-style clause.
[thisArg]: Object
, Value of this
in the callback
.
Returns: *
, The morphed value
_.sift(value, [callback], [thisArg])
Convenience method. Calls _.filter
or _.pick
as appropriate on value
. If value
is not an Array or Object, value
will be returned.
Parameters
value: Object | Array
, Value to filter
or pick
against.
[callback]: Function | Object
, Function to execute, or _.pluck
-style clause.
[thisArg]: Object
, Value of this
in the callback
.
Returns: *
, The sifted value
_.squirt(collection, key, [value])
"Squirts" some key/value pair into each member of an Object or Array. Maybe like the opposite of _.pluck
? Dunno.
Parameters
collection: Object | Array
, Some thing to iterate over. If not an iterable value, collection
will be returned.
key: Object | string
, If the (enumerable) item in collection
is object-like, use this key to set the value. Alternatively, use an object to set multiple values.
[value]: *
, Value to set key
to. Applicable only if key
is a string.
Returns: *
, The squirted collection
Example:
var foo = {} {} {};_ // [{bar: true}, {bar: true}, {bar: true}] // equivalent:var baz = {} {} {};_ // [{bar: true}, {bar: true}, {bar: true}]
_.empty([value])
Empties a value of its enumerable contents.
Parameters
[value]: Object | Array
, Value to empty
Returns: *
, Emptied value, if it's empty-able.
Example:
var foo = a: 1 b: 2 c: 3;_; // {}var bar = 1 2 3;_; // []
_.add([target], [...value])
General-purpose "add this to that" function; skips falsy values. Behavior:
- If given a
target
Array
, return a new Array concatenating only truthy values. - If given a
target
Object
, return a new Object with Array-like keys; thetarget
will be key0
, and each truthy value will increment from there. You can take this value and_.extend
it back into an Array easily. - If given a
target
string
, return a new String with the truthy values concatenated to it. Each value will be coerced to string via itstoString()
method. - If given a
target
boolean
, returntrue
if any values aretrue
; otherwise return the value oftarget
. Each value will be coerced to boolean. - If given a
target
number
, return the number added to the sum of the values. Skips values not parseable to a number. - If given a
target
NaN
, return thetarget
. - If given a
target
Function
, return a function which calls_.add()
, with the first parameter being the value returned bytarget
, and eachvalue
as the remaining parameters.
Parameters
[target]: T
, Value to "add" something to.
[...value]: *
, One or more things to "add" to the target
.
Returns: T
, the same type as target
.
Example:
_; // [1, 2, 3, 4]_; // 'foobar'_ // {0: {herp: 'derp'}, 1: 'bar'}_; // 6_; // Infinity_ // true_2; // 6
Non-Chainable Methods
_.flattenPrototype(value)
Given an object with a non-trivial prototype chain, return its flattened prototype.
Parameters
value: *
, Something with a prototype, hopefully
Returns: Object
, A flattened prototype
_.hasFunction([value], [fnName])
Returns true
if value
is an object with its own function named fnName
.
Parameters
[value]: Object
, Some object-like thing.
[fnName]: String
, Name of Function to look for.
Returns: boolean
_.containsFunction([value], [fnName])
Returns true
if value
is an object with any function named fnName
. Walks the prototype chain.
Parameters
[value]: Object
, Some object-like thing.
[fnName]: String
, Name of Function to look for.
Returns: boolean
_.applicator([func], [args], [ctx])
Generates a function which accepts a value and returns the result of executing a function against that value.
Parameters
[func]: Function | string
, Function to call. If a string, then will atempt to execute a function with the same name within the parameter to the returned function of this function. If omitted, will call _.identity
.
[args]: Array
, Any arguments to pass to func
.
[ctx]: Object
, Context to execute func
in. Defaults to the parameter to the returned function of this function.
Returns: Function
Example:
var foo = _;var bar = 1;; // '1'
_.isDefined([value])
Returns true
if the value is not undefined
.
Parameters
value: *
, Value to inspect
Returns: boolean
_.format(value, [params])
See package format.
_.noop()
It's a no-op.
Example:
// nothing happens._; // nothing happens a second later.;
AngularJS API
The following are only available if you are using AngularJS and have followed the "usage" directions:
Non-Chainable Methods
_.truthy([ctx], [exp])
Evaluates AngularJS expression exp
in context of "object" ctx
for truthiness. The purpose of this is to avoid code like:
if foo && foobar && foobarbaz && foobarbazquux // ...
"Object" means one of: Array
, Function
, Object
, RegEx
, new Number(0)
, and new String('')
.
Parameters
ctx: Object
, Context in which to evaluate exp
.
exp: String
, Valid AngularJS path expression. Assignments not allowed.
Returns: boolean
Example:
var foo = bar: baz: quux: true;_ // true
_.falsy([ctx], [exp])
Evaluates AngularJS expression exp
in context of "object" ctx
for falsiness. The purpose of this is to avoid code like:
if foo && foobar && foobarbaz && foobarbazquux // ...
"Object" means one of: Array
, Function
, Object
, RegEx
, new Number(0)
, and new String('')
.
Parameters
ctx: Object
, Context in which to evaluate exp
.
exp: String
, Valid AngularJS path expression. Assignments not allowed.
Returns: boolean
Example:
var foo = bar: baz: quux: false;_ // true
_.keypath([ctx={}], exp, [value])
Using dot-notation, get or set a value within an object ctx
. Can also be used to create objects.
"Object" means one of: Array
, Function
, Object
, RegEx
, new Number(0)
, and new String('')
.
Parameters
ctx: Object | String
, Context in which to evaluate exp
. If a string, then considered to be a path, and exp
is considered to be the value. Defaults to {}
.
exp: String | *
, If a string, then an AngularJS expression path to be evaluated within ctx
. Otherwise, assumed to be the value
in "setter" mode.
value: *
, If present, sets the value of path exp
.
Returns: * | undefined
, The value of the expression exp
if in "getter" mode, if exp
is a String
; otherwise ctx
.
Throws: If AngularJS expression not parseable by $parse
.
Throws: If value present and keypath is not assignable by
$parse`.
Example:
var foo = bar: baz: quux: true;// get a value_; // true // set a value_; // foofoobarbazspam; // false // create an object dynamically_ // {herp: 'derp'}_ // equivalent
_.isScope([value])
Returns true
if value
is a Scope.
Parameters
[value]: *
, Value to check.
Returns: boolean
_.angularize([scope], [expr], [ctx], [args])
Returns a Function which evaluates an expression or executes a Function within an AngularJS context.
If any parameters are incorrect, no-op will be returned.
Parameters
[scope]: Scope | Function | string
, If a Scope object, then $apply()
will be called with this Scope. Otherwise, $apply()
will be called against $rootScope()
. Note: if expr
is a Function, a Scope is unneccessary, because the Scope has no bearing on what the Function does.
[expr]: string | Function
, If a string, expected to be a valid AngularJS expression. If a Function, then this Function will be passed to $rootScope.$apply()
.
[ctx]: Object
, Context to run expr
in, if expr
is a Function.
[args]: Array
, Args to pass to expr
, if expr
is a Function.
Returns: Function
_.handle([element], [eventName], [callback], [scope])
Convenience function to bind an event to an element, and wrap the callback in an AngularJS context. If any params are omitted, element
is returned. If scope
is passed, automatically unbinds upon $destroy
event.
Parameters
[element]: angular.element | T
, AngularJS Element object. If not, then element
is returned.
[eventName]: String
, Name of event to bind to. If not, then element
is returned.
[callback]: Function
, Callback to execute. If not, then element
is returned.
[scope]: Scope
, If present (and a Scope), then will use to unbind the handler when the Scope is destroyed.
Returns: T
, Parameter element
Example:
element;scope; // is equivalent to: _;
Developing
Clone this module, then execute npm install
within it.
Building
To build, execute:
$ npm run-script build
The created files are placed in the dist/
directory.
Custom Builds
If you have a custom build of LoDash, you can create a build against it; assuming everything this module uses from LoDash is in your build.
Clone this repo, cd
into it, then:
$ npm install$ ./node_modules/.bin/grunt custom --lodash /path/to/custom/lodash.js
You can just use
grunt
if you have installedgrunt-cli
globally.
This will create lodash-decipher.custom.js
, lodash-decipher.custom.min.js
, and lodash-decipher.custom.min.js.map
in the dist/
directory. These files are not under version control.
The Grunt task custom-ng
will create a custom build in the same manner, with the AngularJS extensions included.
Tests
$ npm test
If there were any tests, they'd be executed. TODO: Get on that.
Maintainer
License
Copyright (c) 2014 Decipher, Inc.; Licensed MIT