decorateAfter

Decorate a provided function such that the function's return value is provided as an argument to another function.

Usage

var decorateAfter = require( '@stdlib/utils/decorate-after' );

decorateAfter( fcn, arity, after[, thisArg] )

Decorates a provided function such that the function's return value is provided as an argument to another function.

var abs = require( '@stdlib/math/base/special/abs' );

function negate( v ) {
    return -v;
}

var f = decorateAfter( abs, abs.length, negate );
// returns <Function>

var bool = ( abs.length === f.length );
// returns true

var v = f( -5 );
// returns -5

v = f( 5 );
// returns -5

Decorators are intended to be transparent, meaning that, when interfacing with an API, the decorated API should have the same signature (i.e., number of parameters) as the decorated function. Thus, a typical value for arity is fcn.length. This function does not require equality, however, and the arity argument is allowed to diverge from that of the decorated function. Specifying a differing arity does not affect function evaluation behavior, as the returned function passes all provided arguments to the decorated function.

var abs = require( '@stdlib/math/base/special/abs' );

function negate( v ) {
    return -v;
}

var f = decorateAfter( abs, 0, negate );
// returns <Function>

var bool = ( abs.length === f.length );
// returns false

var v = f( -5 );
// returns -5

v = f( 5 );
// returns -5

To specify the function execution context for after, provide a thisArg argument.

var abs = require( '@stdlib/math/base/special/abs' );

function counter() {
    this.count += 1;
}

var ctx = {
    'count': 0
};

var f = decorateAfter( abs, abs.length, counter, ctx );
// returns <Function>

var v = f( -5 );
// returns 5

v = f( 5 );
// returns 5

var count = ctx.count;
// returns 2

decorateAfter.factory( fcn, arity, after[, thisArg] )

Uses code generation to decorate a provided function such that the function's return value is provided as an argument to another function.

var abs = require( '@stdlib/math/base/special/abs' );

function negate( v ) {
    return -v;
}

var f = decorateAfter.factory( abs, abs.length, negate );
// returns <Function>

var bool = ( abs.length === f.length );
// returns true

var v = f( -5 );
// returns -5

v = f( 5 );
// returns -5

Argument behavior is the same as for decorateAfter above.

Notes

If the after function returns undefined, the returned decorator returns the return value of the decorated function fcn; otherwise, the returned decorator returns the return value of after.
Code generation may be problematic in browser contexts enforcing a strict content security policy (CSP). If running in or targeting an environment with a CSP, avoid using code generation.
For non-native functions, the code generation API supports returning a decorator whose API exactly matches the API of the decorated function, including function length and parameter names. For native functions, due to how native functions serialize to strings, the code generation API generates placeholder parameter names, which are unlikely to match the canonical parameter names. Using placeholder parameter names ensures that the length of the decorator (i.e., number of parameters) matches the decorated function and, except in scenarios involving function source code inspection, will not affect runtime behavior.
For the non-code generation API, the returned decorator supports an arity less than or equal to 10 (i.e., the maximum arity of the returned function is 10). For an arity greater than 10, the returned function has an arity equal to 0. While this violates strict notions of a decorator, for all practical purposes, this is unlikely to be an issue, as the vast majority of functions have fewer than 10 parameters and the need for explicitly checking function length is relatively uncommon.
The decorators returned by the code generation and non-code generation APIs should have the same performance characteristics, and, thus, neither API should have a performance advantage over the other. The main advantage of the code generation API is the ability to return a decorator whose signature exactly matches the signature of a non-native decorated function.
Common use cases for decorating a function with additional actions after invocation include logging, capturing invocation statistics, and validating return values.

Examples

var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
var format = require( '@stdlib/string/format' );
var decorateAfter = require( '@stdlib/utils/decorate-after' );

function count() {
    this.count += 1;
}

function greet() {
    return 'Hello!';
}

function randstr( f ) {
    var str;
    var i;

    str = [];
    for ( i = 0; i < discreteUniform( 1, 10 ); i++ ) {
        str.push( f() );
    }
    return str.join( ' ' );
}

// Create an evaluation context to allow tracking how many times a function is invoked:
var ctx = {
    'count': 0
};

// Decorate a function with a counter:
var f = decorateAfter( greet, greet.length, count, ctx );

// Generate a random greeting:
var str = randstr( f );
// returns <string>

// Check how many times the function was invoked:
var c = ctx.count;
// returns <number>