blutils

    0.8.0 • Public • Published

    Synopsis

    blutils is a utility library for bluebird and a direct fork of qtils.

    stability 2 - unstable license - Unlicense Flattr this

    Build Status Coverage Status Code Climate

    NPM status

    Dependencies

    Note

    When dealing with multiple arguments in promises, it is customary to pass them around as arrays. Until EcmaScript 6 destructuring becomes widely available, this makes promise control flows with multiple promises a bit unpractical when you can't use .spread.

    If you find yourself using .spread a lot but still want to give the array manipulation helpers in this library a try, consider using spread-args to convert functions that take positional arguments into functions that accept a simple argument array.

    Install

    With NPM

    npm install blutils

    From source

    git clone https://github.com/pluma/blutils.git
    cd blutils
    npm install
    make test

    API

    seq(fns...):Function

    Creates a function that will pass its argument to the given sequence of functions and returns a promise that resolves to the sequence's result.

    This is mostly equivalent to thening the functions:

    Promise.cast('qux')
    .then(blutils.seq(
        function(str) {return str.toUpperCase();},
        function(str) {return str.slice(0, 1).toLowerCase() + str.slice(1);}
    ))
    .then(console.log); // 'qUX'

    append(fns...):Function

    Creates a function that will pass its argument to the given sequence of functions and returns a promise that will be resolved to the functions' result appended to the argument.

    If the argument is not an Array, it will be wrapped in one before the result is appended.

    Example:

    Promise.cast('foo')
    .then(blutils.append(
        function(str) {
            return str.replace('f', 'b');
        },
        function(str) {
            return str.replace('oo', 'ar');
        }
    ))
    .then(console.log); // ['foo', 'boo']

    prepend(fns...):Function

    Creates a function that will pass its argument to the given sequence of functions and returns a promise that will be resolved to the functions' result prepended to the argument.

    If the argument is not an Array, it will be wrapped in one before the result is prepended.

    Example:

    Promise.cast('foo')
    .then(blutils.prepend(
        function(str) {
            return str.replace('f', 'b');
        },
        function(str) {
            return str.replace('oo', 'ar');
        }
    ))
    .then(console.log); // ['bar', 'foo']

    tee(fns...):Function

    Creates a function that will pass its argument to the given sequence of functions and returns a promise that will be resolved to the argument when the function's result is fulfilled.

    In other words, tee allows you to add thenable side-effects to a promise chain (without having to modify them so they return their inputs).

    Example without tee:

    Promise.cast('foo')
    .then(function(str) {
        console.log('Result is:', str); // 'Result is: "foo"'
        return str; // Must return the input or next `then` will see `null`
    })
    .then(console.log); // 'foo'

    Example with tee:

    Promise.cast('foo')
    .then(blutils.tee(function(str) {
        console.log('Result is:', str); // 'Result is: "foo"'
    }))
    .then(console.log); // 'foo'

    guard(fn, handleRejection):Function

    Creates a function that will pass its argument to the given function and returns a promise that resolves to the sequence's result or the result of handleRejection if the function fails.

    Naive example without guard:

    frobnicateDoodads()
    .then(embiggenDoodads)
    .catch(recoverFromEmbiggeningFailure) // will also trigger if frobnication fails
    .then(rasterizeDoodads)
    .catch(recoverFromRasterizationFailure) // will also trigger if recovery from embiggening failure fails
    .done(logResults, logFailure);

    Non-naive example without guard:

    frobnicateDoodads()
    .then(function(doodads) {
        return Promise.cast(doodads)
        .then(embiggenDoodads)
        .catch(recoverFromEmbiggeningFailure);
    })
    .then(function(doodads) {
        return Promise.cast(doodads)
        .then(rasterizeDoodads)
        .catch(recoverFromRasterizationFailure);
    })
    .done(logResults, logFailure);

    Example with guard:

    frobnicateDoodads()
    .then(blutils.guard( // only called if frobnication was successful
        embiggenDoodads,
        recoverFromEmbiggeningFailure // only catches embiggening failures
    ))
    .then(blutils.guard( // only called if embiggening was successful
        rasterizeDoodads,
        recoverFromRasterizationFailure // only catches rasterization failures
    ))
    .done(logResults, logFailure);

    eacharg(fns...):Function

    Creates a function that will pass each item in an array to each function and returns a promise that will be resolved to an array containing the results.

    If the number of functions is smaller than the number of items in the array, it will loop over the functions.

    Example:

    Promise.cast(['Foo', 'Bar', 'Qux'])
    .then(blutils.eacharg(
        function(str) {return str.toUpperCase();},
        function(str) {return str.toLowerCase();}
    ))
    .then(console.log); // ['FOO', 'bar', 'QUX']

    allargs(fns...):Function

    Creates a function that will pass its argument to each function and returns a promise that will be resolved to an array containing the results.

    Example:

    Promise.cast(['foo', 'bar', 'qux'])
    .then(blutils.allargs(
        function(arr) {return arr.join('-');},
        function(arr) {return arr.join('+');}
    ))
    .then(console.log); // ['foo-bar-qux', 'foo+bar+qux']

    mutate(mutation:Object):Function

    Creates a function that will mutate its argument by applying the each function of the given mutation object to each property value (or array item) of the argument.

    The function returns a promise that resolves to the mutated object when all mutation results have resolved or is rejected if any of the mutation results are rejected.

    The mutations modify properties of the input object in-place.

    Example:

    Promise.cast(['foo', 'bar', 'qux'])
    .then(blutils.mutate({
        0: function(arg) {return arg.toUpperCase();},
        2: function(arg) {return Promise.cast(arg.toUpperCase());}
    }))
    .then(console.log); // ['FOO', 'bar', 'QUX']

    Nesting example:

    Promise.cast(['foo', 'bar', {qux: 'baz', soup: 'chunky'}])
    .then(blutils.mutate({
        2: {
            qux: function(arg) {return arg.toUpperCase();}
        }
    }))
    .then(console.log); // ['foo', 'bar', {qux: 'BAZ', soup: 'chunky'}]

    splice(offset:int, [count:int], fn:Function):Function

    Creates a function that takes an array as argument and will cut out a slice of length count starting at index offset and replace it with the result of passing the slice to the given function.

    If offset is negative, the index will be determined from the end of the array rather than the start.

    If count is not defined, it will default to the entire length of the array starting at the index.

    Example with array return value:

    Promise.cast(['a', 'b', 'c', 'd', 'e'])
    .then(blutils.splice(1, 2, function(slice) {
        return slice.reverse();
    }))
    .then(console.log); // ['a', 'c', 'b', 'd', 'e']

    Example with non-array return value:

    Promise.cast(['a', 'b', 'c', 'd', 'e'])
    .then(blutils.splice(1, 2, function(slice) {
        return 'x';
    }))
    .then(console.log); // ['a', 'x', 'd', 'e']

    Example with negative offset:

    Promise.cast(['a', 'b', 'c', 'd', 'e'])
    .then(blutils.splice(-4, 2, function(slice) {
        return 'x';
    }))
    .then(console.log); // ['a', 'x', 'd', 'e']

    Example without count:

    Promise.cast(['a', 'b', 'c', 'd', 'e'])
    .then(blutils.splice(1, function(slice) {
        return 'x';
    }))
    .then(console.log); // ['a', 'x']

    Unlicense

    This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

    Install

    npm i blutils

    DownloadsWeekly Downloads

    4

    Version

    0.8.0

    License

    none

    Last publish

    Collaborators

    • pluma