Necessitates Proper Modularity
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    valentinepublic

    \  / _. |  _  ._ _|_ 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(== 'one')
        console.log(== 'two')
        callback(null, 'three')
      }
    , function (c, callback) {
        console.log(== '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!

    install

    npm i valentine

    Downloadsweekly downloads

    192

    version

    2.1.4

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar