ish.type.fn

Function-based type functionality.

Source:

Methods

ish.type.fn.asyncSupport() → {boolean}

Source:
Determines if asynchronous functions are supported in the current environment.
Returns:
Type Description
boolean Value representing if asynchronous functions are supported in the current environment.

ish.type.fn.call(fn, vContextopt, vArguments) → {variant}

Source:
To Do:
  • Refactor all ish.type.fn.call references to use ish.type.fn.run as it has a more consistent interface to the rest of ish.js.
Executes the passed function.
The passed function is executed via function.apply().
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
vContext variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
vArguments variant Value representing the arguments to pass into the passed function.
Note: This value is passed through ish.type.fn.convert to ensure an array.
Returns:
Type Description
variant Value representing the passed function's return value.

ish.type.fn.convert(x) → {Array.<variant>}

Source:
Casts the passed arguments instance, array or single value into an array fit to pass to function.apply().
Parameters:
Name Type Description
x variant Value to interrogate.
Returns:
Type Description
Array.<variant> Value representing the passed value as an array.

[mixin] ish.type.fn.debounce(fn, oOptionsopt) → {function}

Source:
Wraps the passed function, ensuring it cannot be executed until the wait duration has passed without a call being made.
The passed function is executed via function.apply().
From Mixin: ish.type-ex.js must be included for ishJS to access this functionality.
Example
var myEfficientFn = ish.type.fn.debounce(function () {
     // All the taxing stuff you do
   }, 250);
   window.addEventListener('resize', myEfficientFn);
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
oOptions object <optional>
 Value representing the desired options:
Properties
Name Type Attributes Default Description
context variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
wait integer <optional>
 500 Value representing the minimum number of milliseconds (1/1000ths of a second) between each call.
leading boolean <optional>
 false Value representing if the passed function is to be executed immediently on the first call.
Returns:
Type Description
function Function that returns a value representing the passed function's return value from the most recent call.

[mixin] ish.type.fn.inject(fn, oDependencies, bNoCallWhenMissingopt) → {object|boolean|Array.<string>}

Source:
Injects dependencies into the passed function from the passed value.
From Mixin: ish.type-ex.js must be included for ishJS to access this functionality.
Parameters:
Name Type Attributes Default Description
fn function Value representing the function to execute.
oDependencies object Value representing the dependencies to inject.
bNoCallWhenMissing boolean <optional>
 false Value representing if the passed function is to be called if dependencies are missing.
Returns:
Name Type Description
interface object Value representing the following properties:
Properties
Name Type Description
success boolean Value indicating if the passed function was executed.
missing Array.<string> Value indicating the missing dependencies.

ish.type.fn.is(x) → {boolean}

Source:
See:
Determines if the passed value represents a function.
Parameters:
Name Type Description
x variant Value to interrogate.
Returns:
Type Description
boolean Value representing if the passed value represents a function.

ish.type.fn.is.args(x) → {boolean}

Source:
Determines if the passed value represents an arguments instance.
Parameters:
Name Type Description
x variant Value to interrogate.
Returns:
Type Description
boolean Value representing if the passed value represents an arguments instance.

ish.type.fn.is.async(x) → {boolean}

Source:
See:
Determines if the passed value represents an asynchronous function.
Parameters:
Name Type Description
x variant Value to interrogate.
Returns:
Type Description
boolean Value representing if the passed value represents an asynchronous function.

ish.type.fn.metadata(fn) → {object|boolean|boolean|boolean|boolean|string|Array.<string>}

Source:
Determines the metadata about the passed function.
Parameters:
Name Type Description
fn function Value representing the function to execute.
Returns:
Name Type Description
metadata object Value representing the following properties:
Properties
Name Type Description
is boolean Value indicating if the passed function is a valid function.
async boolean Value indicating if the passed function is an async function.
isArrow boolean Value indicating if the passed function is an arrow function expression.
hasParens boolean Value indicating if the passed function has parenthesis in its definition.
Arrow function expressions allow for single parameter definitions to exclude parenthesis, e.g. x => { console.log(x); }.
name string Value indicating the name of the passed function or [anonymous] if one is not specified.
parameters Array.<string> Value indicating the names of the passed function's parameters.

ish.type.fn.mk(x, vDefaultValopt) → {function}

Source:
Casts the passed value into a function.
Parameters:
Name Type Attributes Default Description
x variant Value to interrogate.
vDefaultVal variant <optional>
 ish.type.fn.noop Value representing the default return value if casting fails.
Returns:
Type Description
function Value representing the passed value as a function type.

ish.type.fn.noop()

Source:
Null function with no body and no specified return value.

ish.type.fn.once(fn, oOptionsopt) → {function}

Source:
See:
Wraps the passed function, ensuring it is executed no more than once.
The passed function is executed via function.apply().
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
oOptions object <optional>
 Value representing the desired options:
Properties
Name Type Attributes Default Description
context variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
default variant <optional>
 Value representing the default value to return if the passed function is invalid.
rereturn boolean <optional>
 true Value representing if subsequent calls should return the first return value.
call integer OUT Value set by reference representing the number of calls to the passed function.
Returns:
Type Description
function Function that returns a value representing the passed function's return value or the default value if the passed function is invalid.

ish.type.fn.poll(fn, oOptionsopt) → {function}

Source:
See:
Wraps the passed function, executing it once per wait duration until it returns truthy or the maximum attempts are exhaused.
The passed function is executed via function.apply().
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
oOptions object <optional>
 Value representing the desired options:
Properties
Name Type Attributes Default Description
context variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
wait integer | function <optional>
 500 Value representing the number of milliseconds (1/1000ths of a second) or function called per attempt that returns the number of milliseconds between each call; iWaitMilliseconds = oOptions.wait(iAttemptCount).
maxAttempts integer <optional>
 4 Value representing the maximum number of polling attempts.
callback boolean <optional>
 Value representing the function to be called on completion; oOptions.callback(bPollFunctionReturnedTruthy).
Returns:
Type Description
function Function that executes the passed function once per wait duration until it returns truthy or the maximum attempts are exhaused.

ish.type.fn.poll.expBackoff(iBaseIntervalopt) → {function}

Source:
Calculates the exponential back-off based on the passed base interval and attempt count.
Parameters:
Name Type Attributes Default Description
iBaseInterval integer <optional>
 100 Value representing the number of milliseconds (1/1000ths of a second) to base the exponential interval on, e.g. 100 results in intervals of 100, 200, 400, 800, 1600, etc.
Returns:
Type Description
function Function that returns a value representing the number of milliseconds for the current polling attempt.

[mixin] ish.type.fn.proxy() → {function|function|function}

Source:
Creates a proxy function that forwards calls to all registered functions.
From Mixin: ish.type-ex.js must be included for ishJS to access this functionality.
Returns:
Name Type Description
proxy function Value representing the proxy function that forwards calls to all registered functions along with an interface with the following properties:
Properties
Name Type Description
add function Registers the passed function to the parent proxy function; add(fn):
fnfunctionValue representing the function to register.
Returns:booleanValue representing if the passed function has been successfully registered.
rm function Unregisters the passed function from the parent proxy function; rm(fn):
fnfunctionValue representing the function to unregister.
Returns:booleanValue representing if the passed function has been successfully unregistered.

ish.type.fn.run(fn, vOptionsopt) → {variant}

Source:
Executes the passed function.
The passed function is executed via function.apply().
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
vOptions arguments | Array.<variant> | object <optional>
 Value representing an arguments instance, an array of arguments or an object representing the desired options:
Properties
Name Type Attributes Description
context variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
default variant <optional>
 Value representing the default value to return if the passed function is invalid.
asyncCallback function <optional>
 Value representing the default value to return if the passed function is invalid.
args arguments | Array.<variant> <optional>
 Value representing the arguments to pass into the passed function.
Note: This value is passed through ish.type.fn.convert to ensure an array.
Returns:
Type Description
variant Value representing the passed function's return value or the default value if the passed function is invalid.

ish.type.fn.signature(fn, vAttachToPropertyopt) → {object|function|function|string|Array.<string>|boolean|boolean}

Source:
Allows for the definition and validation of the passed function's signature.
Parameters:
Name Type Attributes Default Description
fn function Value representing the function to define a signature for.
vAttachToProperty boolean | string <optional>
 'signature' Value representing the property name to attach the return value to under the passed fn.
Returns:
Name Type Description
chainedInterface object Value representing a chained interface with the following properties:
Properties
Name Type Description
parameter function Defines the next parameter for the function; parameter(vTest, sErrorMessage):
vTestfunction | stringValue representing the argument validator as a function or string referencing a ish.types.*.is function (e.g. str, int, obj, etc).
sErrorMessagestringValue representing the custom error message to display when an argument fails the vTest.
The order of calls to parameter must match the order of the parameters in the passed function.
validate function Determines if the passed arguments conform to the defined parameter tests; validate(_arguments, bRaiseError):
_argumentsarguments | variant[]Value representing the arguments.
Note: This value is passed through ish.type.fn.convert to ensure an array.
bRaiseErrorbooleanValue representing if an error is to be thrown if an error occurs.
name string Value indicating the name of the passed function or [anonymous] if one is not specified.
parameters Array.<string> Value indicating the names of the passed function's parameters.
valid boolean Value indicating if the passed arguments conform to the function's signature.
fn boolean Value representing the function to define a signature for.

[mixin] ish.type.fn.throttle(fn, oOptionsopt) → {function}

Source:
See:
Wraps the passed function, ensuring it is executed as much as possible without ever executing more than once per wait duration.
The passed function is executed via function.apply().
From Mixin: ish.type-ex.js must be included for ishJS to access this functionality.
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
oOptions object <optional>
 Value representing the desired options:
Properties
Name Type Attributes Default Description
context variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
wait integer <optional>
 500 Value representing the minimum number of milliseconds (1/1000ths of a second) between each call.
leading boolean <optional>
 true Value representing if the passed function is to be executed immediately on the first call.
trailing boolean <optional>
 false Value representing if the passed function is to be executed at the conclusion of the last wait time.
Returns:
Type Description
function Function that returns a value representing the passed function's return value from the most recent call.

ish.type.fn.tryCatch(fn, oOptionsopt) → {function}

Source:
See:
Wraps the passed function, ensuring it is executed within a try...catch block.
The passed function is executed via function.apply().
Parameters:
Name Type Attributes Description
fn function Value representing the function to execute.
oOptions object <optional>
 Value representing the desired options:
Properties
Name Type Attributes Default Description
context variant <optional>
 Value representing the context (e.g. this) the passed function is executed under.
default variant <optional>
 Value representing the default value to return if the passed function errors.
returnObj boolean <optional>
 false Value representing if an object is to be returned representing the result and error.
Returns:
Type Description
function Function that returns a value representing the passed function's return value or the default value if the passed function errors.