Package Exports
- valentine
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (valentine) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
\ / _. | _ ._ _|_ o ._ _
\/ (_| | (/_ | | |_ | | | (/_
JavaScript's Sister, and protector — inspired by Underscore; Valentine provides you with type checking, functional iterators, and common utility helpers such as waterfalls, queues, and parallels; all utilizing native JavaScript methods for optimal speed.
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!