Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Out of service, use Collections — The missing methods of JavaScript
JavaScript
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
CHANGES
LICENSE
README
package.json

README


Provides the missing methods for JavaScript

 - usable as a CommonJS module, in Node
 - usable as a <script> in all web browsers


For Node:

    $ curl http://npmjs.org/install.sh | sh
    $ npm install n-util


As a CommonJS module:

    var UTIL = require("n-util");
    UTIL.unique([1, 1, 2, 3, 3, 4]);


As a <script src="n-util.js"></script>:

    UTIL.unique([1, 1, 2, 3, 3, 4]);


THE API


    no(value)
        returns whether value is null or undefined,
        thus whether it is not safe to grab properties.

    object(value)
        converts values to objects
        
        - returns value.toObject() if available in the object's
          prototype chain but not owned.
        - creates shallow copies of objects
        - converts sequences of [key, value] items into objects,
          using the items(value) missing method
          - any value can have items if it provides a
            value.items() method.
        - returns {} if value is undefined

    array(value)
        converts values to arrays

        - creates shallow copies of all array-like objects,
          including arguments and strings
        - returns value.toArray() if available in the object's
          prototype chain but not owned.
        - uses value.forEach() if available in the object's
          prototype chain but not owned.
        - constructs arrays of [key, value] items from objects,
          using the items(value) missing method
          - any value can have items if it provides a
            value.items() method.
        - returns [] if value is undefined
       
    array.coerce(value)
        returns Arrays unmodified, and uses array(value)
        to convert all other values into arrays.
        
    isArrayLike(value)
        returns whether the value is an array or arguments
        object.

    isArguments(value)
        returns whether the given value is an arguments
        object.

    string(value)
        converts a value to a string.
        - converts null and undefined to an empty string.
        - uses value.toString() if available in the polymorphic
          chain and not owned.
        - uses value.valueOf().toString() generally.

    copy(value)
        creates a shallow copy for the following values:
        - null (null)
        - undefined (undefined)
        - array-like objects (as arrays)
        - dates (passed through)
        - objects (only owned properties reflected,
          no prototype copy)

        array.copy or object.copy are available if the type of the
        value is known and non-polymorphic.

    deepCopy(value)
        creates a deep copy of a given value, recursing on arrays an
        objects, not replicating prototype chains or non-owned
        values.

        Use array.deepCopy or object.deepCopy if the type
        is known and polymorphism would be wasteful.
   
    keys(object)
        returns an array of owned keys for both objects and array-like
        objects.  the keys of an array are the range(0, object.length)

        Use object.keys if the type of object is known and
        polymorphism would be wasteful.

    values(object)
        returns an array of the owned values of both objects and
        array-like objects.  the values of an array is a shallow
        copy of the array.

        Use object.values if the type of object is known
        and polymorphism would be wasteful.
        
    items(object)
        returns an array of the owned [key, value] items of the given
        object.  the items of an array are an enumeration of
        [offset, index] for indexes in the range(0, object.length)

        Use object.items if the type of object is known and
        polymorphism would be wasteful.

    len(object)
        returns the length of an array or object.  The
        length of an object is the number of owned properties.
        - uses object.len() if available in the object's prototype
          chain.
        - uses object.length if available

        Use array.len or object.len if the type is known
        and polymorphism would be wasteful.

    has(object, value)
        returns whether a given value is owned by an object.
        - uses object.has(value) if available in the object's
          prototype chain if not owned.
        - curries on the value if partially applied.

        Use array.has or object.has if the type is known
        and polymorphism would be wasteful.

    get(object, key, default_opt)
        returns the value for a given key or offset in an object,
        array, or string.  if the object does not own the key, or the
        offset is out of the array or string's range, returns the
        default object.  `undefined` qualifies as an owned value if it
        exists.  throws an error if the key does not exist
        if no default is provided.  `undefined` qualifies as
        a provided default; the argument must be literally
        omitted to signal that a default should be used instead
        of throwing an error.
        - uses object.get(key, default_opt) if available in
          the object's prototype chain if not owned.
        - curries on the key and default value once if partially
          applied.

    set(object, key, value)
        sets the value for a given key or offset in the
        given object or array.
        - returns the object for chainability.
        - uses object.set(key, value) if available in the
          object's prototype chain if not owned.
        - curries on the key and then the value if partially
          applied once or twice.
        
    getset(object, key, default_opt)
        returns the value for a given key or offset in an object,
        array, or string.  if the object does not own the key yet,
        or the offset is out of an array's range, sets the value
        before returning.  `undefined` qualifies as an owned
        value if it exists.
        - uses object.getset(key, default) if it exists.
        - curries on the key and default value once if partially
          applied.

    del(object, key)
    del(object, begin, end)
        deletes the key or all values for a range of offsets
        in a given object or array.
        - returns the object for chainability.
        - uses object.del(...) if provided in the prototype chain but
          not owned.
        - curries once on the key or range if partially applied.

        Use array.del if the type is known and polymorphism
        would be wasteful.

    cut(object, key)
        deletes the item for a given key from an object or
        array and returns the corresponding value.
        - uses object.cut(key) if available in the prototype
          chain but not owned.
        - curries on the key if partially applied.

    put(object, key, value)
        operates like set(object, key, value) for objects,
        but displaces an offset if the object is an array,
        such that all subsequent values are shifted right.
        - returns object for chainability.
        - uses object.put(key, value) if available on the prototype
          chain but not if it is owned.
        - curries on key and value if partially applied.

        Use array.put if the type is known and polymorphism
        would be wasteful.

    first(value)
        returns the value at the first offset of an array
        or array-like object.
        - use value.first() if available on the prototype chain
          but not owned.

        Use array.first if the type is known and polymorphism
        would be wasteful.

    last(value)
        returns the value at the last offset of an array or
        array-like object.
        - use value.last() if available on the prototype chain
          but not owned.

        Use array.last if the type is known and polymorphism
        would be wasteful.

    update(object, other)
        shallowly copies the owned values of other over the object.
        - returns the object for chainability
        - uses object.update(other) if available on the prototype
          chain but not owned.
        - curries on the other object once.

        Use object.update if the type is known and polymorphism
        would be wasteful.

    deepUpdate(object, other)
        deeply copies the owned values of other over this object,
        recursing on arrays and object.
        - uses object.deepUpdate(other) if available on the prototype
          chain but not owned, recursively.
        - returns the object for chainability
        - curries on the other object once.

        Use object.deepUpdate if the type is known and polymorphism
        would be wasteful.

    complete(object, other)
        shallowly copies the owned values of other into this
        object if such keys do not already exist.
        - uses object.complete(other) if available on the prototype
          chain but not owned, recursively.
        - returns the object for chainability
        - curries on the other object once.

        Use object.complete if the type is known and polymorphism
        would be wasteful.

    deepComplete(object, other)
        deeply copies the owned properties of other into this
        object if such keys do not already exist.
        - uses object.deepComplete(other) if available on the
          prototype chain but not owned, recursively.
        - returns the object for chainability.
        - curries on the other object once.

        Use object.deepComplete if the type is known and polymorphism
        would be wasteful.

    remove(object, value)
        removes a value from an array (O(n)).
        - uses object.remove(value) if available in the prototype
          chain but not owned.

    range(length)
    range(start, stop)
    range(start, stop, step)
        - constructs an array of integers in the given range
        - NOT polymorphic

    forEach(array, callback, that_opt)
        calls back on each value in the array, using
        array.coerce, such that it can be used
        to iterate over the items of objects or other
        values that provide a toArray or forEach
        method in their prototype chain after owned
        properties.
        
        - returns the array for chainability

    forEachApply(arrayOfArrays, callback, that_opt)
        calls back variadically, using apply, using each
        array.  uses array.coerce on the arrayOfArrays
        such that it can be used to iterate over the items
        of objects or other values that provide a toArray
        or forEach method in their prototype chain after
        owned properties.

        forEachApply({
            "a": 10,
            "b": 20
        }, function (key, value) {
        })

        - returns the array for chainability

    map(array, callback, that_opt)
        Analogous to forEach but returns the respective
        values of each callback in an array.

    mapApply(array, callback, that_opt)
        Analogous to forEachApply but returns the respective
        values of each callback in an array.

    every(array, callback, that_opt)
        Applies the callback to each value in the array
        (after coercion) and returns whether all of
        the returned values were truthy, shorting on
        the first falsy value.
        - curries on the callback and that object once.
        - uses array.every(callback, that) if available
          in the prototype chain but not owned.

    some(array, callback, that_opt)
        Applies the callback to each value in the array
        (after coercion) and returns whether any of the
        returned values were truthy, shorting on the
        first truthy value.
        - curries on the callback and that object once.
        - uses array.some(callback, that) if available
          in the prototype chain but not owned.
       
    all(array)
        returns whether all of the values in the array
        are truthy.
        - uses array.all() if available in the prototype
          chain but not owned.

    any(array)
        returns whether any value in the array is truthy.
        - uses array.any() if available in the prototype
          chain but not owned.

    reduce(array, callback(accumulated, value, index, array), basis_opt)
        reduces an array by iteratively accumulating the return value
        of the callback, given the current accumulation and the next
        value.  the first accumulated value is the basis or undefined.
        - uses array.reduce if provided in the prototype chain and not
          owned.

    reduce(array, callback(accumulated, value, index, array), basis_opt)
        reduces an array by iteratively accumulating the return value
        of the callback, given the current accumulation and the
        previous value.  the first accumulated value is the basis or
        undefined.
        - uses array.reduceRight if provided in the prototype chain
          and not owned.

    zip(...)
        returns an array of the respective values of each argument,
        coercing non-array values.

    transpose(matrix)
        returns the transpose of an array of arrays, such that
        the rows and columns are swapped.  transpose is the
        inverse of itself, and equivalent to zipping variadically.

    enumerate(array, start_opt)
        returns an array of [offset, value] items for the
        values in a given array, array-like object, or
        object converted to an array using toArray or forEach.
        - start defaults to 0

    is(a, b)
        returns whether two objects are identical by reference.
        unlike pure ===, "is" is reflexive and treats
        negative and positive zero and infinity as distinct.

    eq(a, b)
        returns whether to values are deeply equal by type
        and value.
        - use a.eq(b) if available in the prototype chain and
          not owned, recursively.
        - curries on second value if partially applied.

        Use array.eq or object.eq if the type is known
        and polymorphism would be wasteful.

    ne(a, b)
        !eq(a, b)
        - uses a.ne(b) if available in the prototype chain
          and not owned.
        - curries on the second value if partially applied.

    lt(a, b)
        returns whether a is less than b.  operates
        on arrays recursively.
        - uses a.lt(b) if available in the prototype chain
          and not owned.
        - curries on the second value if partially applied.

        array.lt

    gt(a, b)        
        returns whether a is greater than b.
        !(lt(a, b) || eq(a, b))
        - uses a.gt(b) if available in the prototype chain
          and not owned.
        - curries on the second value if partially applied.

    le(a, b)
        returns whether a is less than or equal to b.
        lt(a, b) || eq(a, b)
        - uses a.le(b) if available in the prototype chain
          and not owned.
        - curries on the second value if partially applied.

    ge(a, b)
        returns whether a is greater than or equal to b.
        lt(a, b) || eq(a, b)
        - uses a.ge(b) if available in the prototype chain
          and not owned.
        - curries on the second value if partially applied.

    mul(a, b)
        multiplies numbers and strings by numbers.
        - uses a.mul(b) if available in the prototype chain
          and not owned.
        - curries on the second value if partially applied.

        Use string.mul(a, b) if a is known to be a string
        and polymorphism is wasteful.

    compare(a, b)
        returns a number such that a as compared to be
        is equivalent to that value as compared to 0.
        for example, if a is less than b, compare will
        return a value that is less than zero.
        Operates on numbers, strings, and arrays recursively.
        Object comparison always returns 0.
        - uses a.compare(b) if available in the prototype
          chain and not owned.
        - curries on the second value if partially applied.

    by(callback)
        returns a comparator, like compare, that will compare
        values based on the comparison of the value returned
        by the callback.

    sort(array, compare_opt)
        sorts an array, using array.sort(compare), where compare
        defaults to deep comparison.  Object comparison is stable.
        
        If by(relation) is used to generate the comparator, sort
        applies a Schwartzian transform which renders higher
        performance generally for arrays that are longer than 3 by
        guaranteeing that the relation will only be used on each value
        once.

    sorted(array, compare_opt)
        returns a sorted copy of given array, using the
        given comparator, or the default comapre function above.

    reverse(array)
        reverses an array in place.

    reversed(array)
        returns a reversed copy of an array.

    hash(object)
        returns a string representing a "hash" of the given
        object, suitable for slotting arbitrary objects
        in another object for high-performance look-ups.
        - uses object.hash() if available in the prototype chain
          and not owned.
        - defaults to stringifying the object, which will perform
          poorly (O(n)) if used to slot objects.

    unique(values, eq_opt, hash_opt)
        returns an array that only contains each equivalent
        object in values once.  Uses "hash" for higher performance
        look-ups of numbers and objects that implement that method,
        and uses "eq" to distinguish equivalent objects.
        "eq" and "hash" can be independently overridden.

    escape(string, strictlyForJson_opt)
        escapes non-printable and unicode characters with
        back-slashes, like \b, \t, \n, \f, \r, \", \\,
        \xff, \uffff.  If strictlyForJson is truthy,
        does not use single-byte \xff encoding.

    enquote(string, strictlyForJson_opt)
        produces a double-quoted, escaped version of the
        given string.

    expand(string, tabLength_opt)
        converts all tabs in a string into a visually
        equivalent number of spaces, assuming that the
        text begins at column 0.
        - tab length is 4 by default

    trimBegin(string)
        trims white space on the left side of a string

    trimEnd(string)
        trims white space on the right side of a string

    trim(string)
        trims white space on both sides of a string

    padBegin(padding, length, pad_opt)
        pads a string with the padding on the left, "0" by default
        until it is at least length-long.
        
    padEnd(padding, length, pad_opt)
        pads a string with the padding on the right, "0" by default
        until it is at least length-long.
        
    splitName(string)
        splits a name into a string of its component words,
        regardless of the case convention.  Respects
        acronyms as single words, such that:

        >>> splitName("XMLHttpRequest")
        ["XML", "Http", "Request"]

    joinName(delimiter, parts)
        joins the words of a name into a single string,
        using the given delimiter between numbers.
        - if delimiter is undefined, it defaults to "_" 
    
    upper(value, delimiter_opt)
        returns an "UPPERCASE" or "UPPER_CASE" (if a delimiter is
        provided) variant of the given string, regardless of the input
        case convention.
    
    lower(value, delimiter_opt)
        returns an "lowercase" or "lower_case" (if a delimiter is
        provided) variant of the given string, regardless of the input
        case convention.
    
    camel(value, delimiter_opt)
        returns a "camelCase" variant of the given string, regardless
        of its case convention.

    title(value, delimiter_opt)
        returns a "TitleCase" or "Title Case" (if a delimiter is
        provided) variant of the given string, regardless of its
        original case convention.

Something went wrong with that request. Please try again.