vigour-util

vigour-util

npm install vigour-util

This is a collection of small utility functions which can be required individually.

Running the tests

npm test expects vtest to exist, so if you want to run the tests, you'll need to npm i -g vigour-test first, which will allow the tests to be run in the context of a browser (Nightmare). See vigour-test

---

var valid = isEmail(val)

Checks whether provided parameter looks like a valid e-mail address

• val (string) - the string to check
• returns (boolean) valid - true if val is a valid e-mail address, false otherwise

var isEmail = require('vigour-util/is/email')
isEmail('dev@vigour..io') // false
isEmail('[e-mail]') // true

var looksLikeHash = isHash(val)

Checks if a string looks like a hash generated by the hash utility

• val (string) - the string to check
• returns (boolean) looksLikeHash - true if val looks like a hash, false otherwise

var isHash = require('vigour-util/is/hash')
isHash('asd654') // true

var runningInNode = isNode()

• returns runningInNode - true if in node context, false otherwise

var isNode = require('vigour-util/is/node')
isNode() // true or false

var finiteNumber = isNumber(value)

This just calls lodash.isfinite internally. See those docs

• value (any) - The value to check
• returns (boolean) finiteNumber - Returns true if value is a finite number, false otherwise

var isNumber = require('vigour-util/is/number')
isNumber(2) // true
isNumber('2') // false

var looksLikeNumber = isNumberLike(val)

Checks whether provided parameter looks like a number

• val (any) - the value to check
• returns (boolean) looksLikeNumber - true if val looks like a number, false otherwise

var isNumberLike = require('vigour-util/is/numberlike')
isNumberLike('2') // true
isNumberLike('a') // false

var stream = isStream(val)

Checks whether provided argument is a stream

• val (object) - the object to check
• returns (boolean) stream - true if val is a stream, false otherwise

var stream = require('stream')
var rs = new stream.Readable()
var isStream = require('vigour-util/is/stream')
isStream(rs) // true

var readable = isStream.readable(val)

Checks whether provided argument is a readable stream

• val (object) - the object to check
• returns (boolean) readable - true if val is a readable stream, false otherwise

var stream = require('stream')
var rs = new stream.Readable()
var isStream = require('vigour-util/is/stream')
isStream.readable(rs) // true

var writable = isStream.writable(val)

Checks whether provided argument is a writable stream

• val (object) - the object to check
• returns (boolean) writable - true if val is a writable stream, false otherwise

var stream = require('stream')
var rs = new stream.Readable()
var isStream = require('vigour-util/is/stream')
isStream.writable(rs) // false

var touch = isTouch()

Checks if we're running in a touch-enabled context

• returns (boolean) touch - true if we're in a touch-enabled context, false otherwise

var isTouch = require('vigour-util/is/touch')
isTouch() // false unless you're using a touch-enabled device

var valid = isUrl(val, [options])

Checks if a string is a valid url

• val (string) - the string to check

• [options] (object) - defaults to {}

• options.requireProtocol {boolean} - set to true if you only want URLs with a protocol to be considered valid. Defaults to false

• returns (boolean) valid - true if val is a valid url, false otherwise

var isUrl = require('vigour-util/is/url')
isUrl('http://perdu.com') // true
isUrl('boom') // false

var plain = isPlainObj(obj)

Checks whether an object is a plain object (excludes streams, buffers, base and null) (Compatible with vigour-base)

• obj (object) - the object to check
• returns (boolean) plain - true if obj is a plain object, false otherwise

var isPlainObj = require('vigour/util/is/plainobj')
isPlainObj({}) // true
isPlainObj(new Base({})) // false

var removed = isRemoved(base)

Checks if a property has been removed (Specific to vigour-base)

• base (Base) - the property to check
• returns (boolean) removed - true if base property has been removed, false otherwise

var isRemoved = require('vigour-util/is/removed')
var Base = require('vigour-base')
var base = new Base({ bad: true })
base.bad.remove()
isRemoved(base.bad) // true

var emptyBase = isEmpty(obj)

Checks if a Base object is empty (Specific to vigour-base)

• obj (object) - the object to check for emptiness
• returns (boolean) emptyBase - true if obj is considered empty, false otherwise

var isEmpty = require('vigour-util/is/empty')
var Base = require('vigour-base')
isEmpty(new Base({})) // true
isEmpty(new Base({ awesome: true })) // false

Checks whether a key is part of an array, allowing for prefixed keys

var found = pathContains(path, key)

Checks whether a key is part of an array, allowing for prefixed keys

• path (array) - the array to look in
• key (string) - the key to check for
• returns (boolean) found - true if key is found in array, false otherwise

var pathContains = require('vigour-util/path/contains')
pathContains(['a','awesome:b','c'], 'b') // true

uuid

.val

A process-specific unique ID, generated on require

var uuid = require('vigour-util/uuid')
uuid.val // 'oj0beu'

var id = uuid.generate()

Generates a unique ID

• returns (string) id - A unique ID

var uuid = require('vigour-util/uuid')
uuid.generate() // '14hdmru'

define(props)

Defines new (or modifies existing) properties (using Object.defineProperty) on an object passed to define as this, setting configurable: true by default

• props (object) - Properties to set

var define = require('vigour-util/define')
var subject = {}
var props = [
  { one: true },
  { two: function () {
      console.log('do nothing')
    }
  }
]
define.apply(subject, props)

descriptors(props)

Like Object.getOwnPropertyDescriptor, but goes along the prototype chain and gets the descriptors for all properties.

• props (object) - the properties to get the descriptors for

var descriptors = require('vigour-util/descriptors')
descriptors({ a: 'a', b: 'b' })
/*
  {
    a: {
      value: 'a',
      writable: true,
      enumerable: true,
      configurable: true
    },
    b: {
      value: 'a',
      writable: true,
      enumerable: true,
      configurable: true
    }
  }
*/

var flat = flatten(subject, [seperator])

Transforms a deep object into an object of single depth where keys are a path and values are leafs of the original object.

• subject (object) - Object that needs to be flattened
• [seperator] (string) - Optional seperator sign, defaults to '.'
• return (object) flat - Object with delimited keys

var flatten = require('vigour-util/flatten')
flatten({ a: { b: 'c', d: 'e' } }) // { 'a.b': 'c', 'a.d': 'e'}
flatten({ a: { b: 'c', d: 'e' } }, '/') // { 'a/b': 'c', 'a/d': 'e'}

var hashOfKey = hash(key, seed)

Hashing utility optimized for speed, not collision avoidance. Produces alpha-numeric hashes between 5 and 7 characters long inclusively.

• key (string) - the string to hash
• seed (number) - a seed for hashing
• returns (string) hashOfKey - The created hash

var hash = require('vigour-util')
hash('Any sting in the world!!!') // '16hck72'

var included = include(target, thing)

Distinctly adds one or multiple items (in an object or array) to a target array. Doesn't duplicate items.

• target (Array) - target array
• thing - the thing to be included in the array. If object or array, it will go through it and add all values to the target array.
• returns (Array) included - Array representing the included items (duplicates removed)

var include = require('vigour-util/include')
var target = [1]
include(target, [2, 1, 3]) // returns [2, 3]
console.log(target) // logs [1, 2, 3]

merge

Obsolete: This function has been removed in version 2. Use lodash.merge instead.

regenerator()

Like Babel's regenerator, but much more compact. Brought to you by Facebook, but bundled in vigour-util for ease-of-use. See the docs

setwithpath

Obsolete: This function has been removed in version 2. Use lodash.set instead.

var obj = unflatten(subject, [seperator])

Opposite of flatten. Unflattens an object with delimited keys

• subject (object) - Object that needs to be unflattened
• [seperator] (string) - Optional seperator sign
• return (object) obj - Nested Javascript object

var unflatten = require('vigour-util')
unflatten({
  'a.b.c': 'd'
})
/*
{
  a: {
    b: {
      c: 'd'
    }
  }
}
*/

var ref = getReference(obj)

Get's the referenced object (Specific to vigour-base)

• obj (object) - the reference we want to follow
• returns (object) ref - The referenced object or undefined

var Base = require('vigour-base')
var getReference = require('../../get/reference')

var a = new Base({})
var b = new Base(a)
getReference(b) // a

enhanceRequire([options])

In node, modifies the behaviour of require so that it ignores paths containing .css, .less, .scss, .sass, and any other paths indicated via the exclude option.

Outside of node (browserify, webpack, etc.), this function does nothing.

• [options] (object) - Options to further define the behaviour of require:

• • {boolean} options.package : set to true to convert require('package.json') to JSON.parse(require(process.cwd() + '/package.json'))
• • {string|regexp|function|array} options.exclude : paths containing the specified string, or matching the specified regexp, or for which specified function returns true, will be excluded. If an array is provided, each element is treated exactly the same as options.exclude and only paths which aren't excluded by any item will be required.

var enhanceRequire = require('vigour-util/require')
enhanceRequire({
  package: true,
  exclude: '/scratch/'
})
require('styles.less') // ignored in node, processed elsewhere
// Don't forget to add a browserify transform or similar for non-node
var pkg = require('package.json') // pkg is the parsed package from the current working directory
require('')
enhanceRequire.restore()