\ / _. | _ ._ _|_ o ._ _
\/ (_| | (/_ | | |_ | | | (/_
Deprecation notice
As of version 2.0.0 — Valentine no longer supports <= IE8 and <= Safari 4. It's been real, but time to move on. To access this level of support, use the 1.8 tag.
Browser usage:
<script src="valentine.js"></script>
<script>
v.forEach(['a', 'b', 'c'], function (letter) {
})
</script>Node users
npm install valentinevar v = require('valentine')
// showcase object style
v(['a', 'b', 'c']).map(function (letter) {
return letter.toUpperCase()
}).join(' '); // => 'A B C'API
iterators
-
v.each(array || object, callback[, scope]) => void
-
v.map(array || object, callback[, scope]) => array
-
v.every(array || object, *callback[, scope]) => boolean
-
v.some(array || object, *callback[, scope]) => boolean
-
v.filter(array || object, *callback[, scope]) => array || object
-
v.reject(ar, *callback[, scope])
-
v.indexOf(ar, item[, start])
-
v.lastIndexOf(ar, item[, start])
-
v.reduce(ar, **callback, memo[, scope])
-
v.reduceRight(ar, **callback, memo[, scope])
*callback is defined as:
// when array
function callback(item, index, array) {
}
// when object
function callback(key, value, object) {
}**calback is defined as:
function callback(memo, item, index, array) {
}utility
- v.extend(obj[, obj2[, obj3[...]]]) => object
- v.merge(ar1, ar2) => array (ar1 modified)
- v.pluck(array||object, key) => array
- v.toArray(sparse) => array (duh)
- v.size(array) => number
- v.find(array, key) => *value
- v.compact(array) => array
- v.flatten(array) => array
- v.uniq(array) => array
- v.first(array) => *value
- v.last(array) => *value
- v.keys(object) => array
- v.values(object) => array
- v.trim(string) => string
- v.bind(scope, fn, [curried args]) => function
- v.curry(fn, [curried args]) => function
- v.inArray(array, needle) => boolean
- v.memo(fn, hasher) => function
// use memo to cache expensive methods
var getAllTheDom = v.memo(function () {
return v(document.getElementsByTagName('*')).toArray()
})
getAllTheDom().each(modifier)parallel api
- v.parallel([fn args]) => void
v.parallel(
function (fn) {
getTimeline(function (e, timeline) {
fn(e, timeline)
})
}
, function (fn) {
getUser(function (e, user) {
fn(e, user)
})
}
, function (e, timeline, user) {
if (e) return console.log(e)
ok(timeline == 'one', 'first result is "one"')
ok(user == 'two', 'second result is "two"')
}
)waterfall api
- v.waterfall([fn args])
- v.waterfall([fn1, fn2<, fn3>], callback)
v.waterfall(
function (callback) {
callback(null, 'one', 'two')
}
, function (a, b, callback) {
console.log(a == 'one')
console.log(b == 'two')
callback(null, 'three')
}
, function (c, callback) {
console.log(c == 'three')
callback(null, 'final result')
}
, function (err, result) {
console.log(!!err == false)
console.log(result == 'final result')
}
)series api
- similar to
waterfallexcept passing along args to next function is not a concern - v.series([fn1, fn2<, fn3>], callback)
v.series([
function (callback) {
setTimeout(callback, 2000)
}
, function (callback) {
process.nextTick(callback)
}
, function (callback) {
callback(null)
}]
, function (err) {
console.log('done')
}
)Queue api
- v.queue([fn args])
var it = v.queue(
function () {
console.log('one')
it.next()
}
, function () {
console.log('two')
it.next()
}
, function () {
console.log('three')
}
)
it.next()throttle, debounce, throttleDebounce
- v.throttle(ms, fn, opt_scope) => function
- v.debounce(ms, fn, opt_scope) => function
- v.throttleDebounce(throttleMs, debounceMs, fn, opt_scope) => function
window.onscroll = v.throttle(50, function (e) {
// expensive scroll function
})
window.mousemove = v.debounce(500, function (e) {
// user has paused momentarily
})
textarea.onkeypress = v.throttleDebounce(20000, 1000, function () {
// autosave(this.value)
// called after 1s if not called again within 1s
// but guaranteed to be called within 20s
})type checking
Each method returns a boolean
- v.is.func(o)
- v.is.string(o)
- v.is.element(o)
- v.is.array(o)
- v.is.arrLike(o)
- v.is.num(o)
- v.is.bool(o)
- v.is.args(o)
- v.is.empty(o)
- v.is.date(o)
- v.is.nan(o)
- v.is.nil(o)
- v.is.undef(o)
- is.regexp(o)
- v.is.obj(o)
Object Style
v(['a', 'b', 'c']).map(function (letter) {
return letter.toUpperCase()
}); // => ['A', 'B', 'C']Chains
v(['a', 'b', [['c']], 0, false,,,null,['a', 'b', 'c']])
.chain().flatten().compact().uniq().map(function (letter) {
return letter.toUpperCase()
}).value(); // => ['A', 'B', 'C']Ender Support
ender add valentine// available as a top level method on `$`
$.v(['a', ['virus'], 'b', 'c']).reject(function (el, i) {
return $.is.arr(el[i])
})
// top level methods in bridge
$.each
map
merge
extend
toArray
keys
values
trim
bind
curry
parallel
waterfall
inArray
queueOr just require the valentine module
!function (v) {
v(['a', ['virus'], 'b', 'c']).reject(function (el, i) {
return v.is.arr(el[i])
})
}(require('valentine'))Developers
Care to contribute? Make your edits to src/valentine.js and get your environment up and running
npm install
make
make test
open tests/index.htmlHappy iterating!