JavaScripts Functional Sister
JavaScript Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
make update docs Apr 26, 2013
src Merge branch 'master' of github.com:adriengibrat/valentine Sep 13, 2014
tests new `v.series` with tests Jul 16, 2014
.gitignore - all tests for iters and utils passing May 2, 2011
.travis.yml new browser support with updated readme Feb 15, 2014
Makefile - new AMD support Sep 16, 2011
README.md
package.json 2.1.4 Jul 20, 2015
valentine.js
valentine.min.js Merge branch 'master' of github.com:adriengibrat/valentine Sep 14, 2014

README.md

\  / _. |  _  ._ _|_ o ._   _
 \/ (_| | (/_ | | |_ | | | (/_

Build Status 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 valentine
var 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 waterfall except 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
  queue

Or 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.html

Happy iterating!