extra-async-function 1.1.8

A collection of ways for transforming async functions.
📦 Node.js, 🌐 Web, 📜 Files, 📰 JSDoc, 📘 Wiki.

An async function is a function that delivers its result asynchronously (through Promise). This package is an variant of extra-function, and includes methods for transforming async functions. The result of an async function can be manipulated with negate. If a pure async function is expensive, its results can cached with memoize. Parameters of a function can be manipulated with reverse, spread, unspread, [wrap], [unwrap]. reverse flips the order of parameters, spread spreads the first array parameter of a function, unspread combines all parameters into the first parameter (array), [wrap] adds ignored parameters to the left/right of a function's parameters, and [unwrap] removes common prefix and suffix parameters to a function (by passing known constant values as prefix/suffix). If you want some functional behavior, compose, composeRight, curry, and curryRight can be used. composeRight is also known as pipe-forward operator or function chaining. If you are unfamiliar, Haskell is a great purely functional language, and there is great haskell beginner guide to learn from.

To control invocation time of a function, use delay. A function can be rate controlled with [limitUse], debounce, debounceEarly, throttle, throttleEarly. [limitUse] controls the number of times a function can be called, and is useful when you want to enforce a function to be called only once, the first n times (before), or after n times. debounce and debounceEarly prevent the invocation of a function during hot periods (when there are too many calls), and can be used for example to issue AJAX request after user input has stopped (for certain delay time). throttle and throttleEarly can be used to limit the rate of invocation of a function, and can be used for example to minimize system usage when a user is constantly refreshing a webpage. Except [limitUse], all rate/time control methods can be flushed (flush()) to invoke the target function immediately, or cleared (clear()) to disable invocation of the target function.

In addition, is, [signature], name, [parameters], and [arity] obtain metadata (about) information on an async function. To attach a this to a function, use bind. A few generic async functions are also included: [SLEEP].

This package is available in both Node.js and Web formats. The web format is exposed as extra_async_function standalone variable and can be loaded from jsDelivr CDN.

Stability: Experimental.

const asyncFunction = require('extra-async-function');
// import * as asyncFunction from "extra-async-function";
// import * as asyncFunction from "https://unpkg.com/extra-async-function/index.mjs"; (deno)

// 1. Basic tests.
async function example1() {
  var a = asyncFunction.composeRight(async x => x*x, async x => x+2);
  await a(10);
  // → 102

  var a = asyncFunction.curry(async (x, y) => x+y);
  await a(2)(3);
  // → 7

  var a = asyncFunction.unspread(async (...xs) => Math.max(...xs));
  await a([2, 3, 1]);
  // → 1.25
}
example1();

Index

Property	Description
ARGUMENTS	Resolve all the arguments passed, as an array.
NOOP	Do nothing.
IDENTITY	Return the same (first) value.
COMPARE	Compare two async values.

name	Get the name of a function.
length	Get the number of parameters of a function.

bind	Bind this-object, and optional prefix arguments to a function.

call	Invoke a function with specified this-object, and arguments provided individually.
apply	Invoke a function with specified this-object, and arguments provided as an array.

is	Check if value is an async function.
isGenerator	Check if value is a generator function.

contextify	Contextify a function by accepting the first parameter as this-object.
decontextify	Decontextify a function by accepting this-object as the first argument.

negate	Generate a result-negated version of an async function.

memoize	Generate result-cached version of an async function.

reverse	Generate a parameter-reversed version of a function.
spread	Generate a (first) parameter-spreaded version of a function.
unspread	Generate a (first) parameter-collapsed version of a function.
attach	Attach prefix arguments to leftmost parameters of a function.
attachRight	Attach suffix arguments to rightmost parameters of a function.

compose	Compose async functions together, in applicative order.
composeRight	Compose async functions together, such that result is piped forward.
curry	Generate curried version of a function.
curryRight	Generate right-curried version of a function.

defer	Generate deferred version of a function, that executes after the current stack has cleared.
delay	Generate delayed version of a function.

restrict	Generate restricted-use version of a function.
restrictOnce	Restrict a function to be used only once.
restrictBefore	Restrict a function to be used only upto a certain number of calls.
restrictAfter	Restrict a function to be used only after a certain number of calls.

debounce	Generate debounced version of a function.
debounceEarly	Generate leading-edge debounced version of a function.
throttle	Generate throttled version of a function.
throttleEarly	Generate leading-edge throttled version of a function.