go-fns
Version:
Utility functions for functions.
367 lines (227 loc) • 11.6 kB
Markdown
# Go Functions
**Utility functions for functions.**
[](https://github.com/koyote130708/go-fns#documentation)
[](https://www.paypal.com/donate/?business=T7Q29NNMZVW98\&no_recurring=0\&item_name=Your+support+will+help+us++continue+our+work+and+improve+the+quality+of+our+products.+Thank+you!\¤cy_code=USD)
* **version**: 1.0.0
* **license**: GNU LGPLv3
<br />
## Installation
```javascript
npm i go-fns
```
or
```javascript
yarn add go-fns
```
<br />
## Usage
### ES6
```javascript
import { not } from 'go-fns'
[1, 2, 3.1].filter(not(Number.isInteger)); // => [3.1]
```
### Node
```javascript
const { not } = require('go-fns');
[1, 2, 3.1].filter(not(Number.isInteger)); // => [3.1]
```
### Web browser
```javascript
<script src="dist/go-fns.min.js"></script>
<script>
const { not } = Functions;
[1, 2, 3.1].filter(not(Number.isInteger)); // => [3.1]
</script>
```
<br />
## Documentation
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
#### Table of Contents
* [Utility](#utility)
* [pipe](#pipe)
* [Parameters](#parameters)
* [Examples](#examples)
* [spread](#spread)
* [Parameters](#parameters-1)
* [Examples](#examples-1)
* [attempt](#attempt)
* [Parameters](#parameters-2)
* [Examples](#examples-2)
* [repeat](#repeat)
* [Parameters](#parameters-3)
* [Examples](#examples-3)
* [delay](#delay)
* [Parameters](#parameters-4)
* [Examples](#examples-4)
* [Logic](#logic)
* [and](#and)
* [Parameters](#parameters-5)
* [Examples](#examples-5)
* [or](#or)
* [Parameters](#parameters-6)
* [Examples](#examples-6)
* [xor](#xor)
* [Parameters](#parameters-7)
* [Examples](#examples-7)
* [nor](#nor)
* [Parameters](#parameters-8)
* [Examples](#examples-8)
* [not](#not)
* [Parameters](#parameters-9)
* [Examples](#examples-9)
### Utility
#### pipe
Creates a function that executes a series of functions in the order provided.
First it passes the parameters to the first function and then the output
is used as the input for the next function in the sequence,
and so on until it reaches the end and finally it returns the output of the last function.
##### Parameters
* `fns` **...[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The functions to execute sequentially.
##### Examples
```javascript
pipe(Math.floor)(4.5); // => 4
pipe(Math.floor, Math.sqrt)(4.5); // => 2
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if any of the given values is not a function, null or undefined.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that sequentially executes the given functions.
**Meta**
* **since**: 1.0.0
#### spread
* **See**: [Spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax)
* **See**: [Function.prototype.apply](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply)
Creates a function that takes an array of values and passes the values to the given function as individual parameters.
##### Parameters
* `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The function to execute with individual parameters.
##### Examples
```javascript
function sum(a, b) {
return a + b;
}
spread(sum)([1, 2]); // => 3
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if <code>fn</code> is not a function.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that passes an array of values to the given function as individual parameters.
**Meta**
* **since**: 1.0.0
#### attempt
Attempts to execute a function and returns the result or if there was an error, the error object caught.
##### Parameters
* `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The function to attempt.
* `args` **...any?** The arguments for the function.
##### Examples
```javascript
attempt(JSON.parse, "1"); // => 1
attempt(JSON.parse, ""); // => SyntaxError
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if <code>fn</code> is not a function.
Returns **(any | [Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error))** The result of executing the function or the error object caught if there was an error.
**Meta**
* **since**: 1.0.0
#### repeat
Executes a function for a specified number of times and returns the results in a new array.
##### Parameters
* `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The function to execute.
* `count` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** The number of times to execute. (optional, default `0`)
* `args` **...any?** The arguments for the function.
##### Examples
```javascript
repeat(Math.floor, 3, 1.5); // => [1, 1, 1]
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if <code>fn</code> is not a function.
Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** The new array containing the results.
**Meta**
* **since**: 1.0.0
#### delay
* **See**: [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)
Executes a function after a specified number of milliseconds with the arguments provided.
##### Parameters
* `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The function to execute after a delay.
* `delay` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** The number of milliseconds to wait before executing the function. (optional, default `0`)
* `args` **...any?** The arguments for the function.
##### Examples
```javascript
delay(log, 1000, "hi"); // => prints "hi" after 1 second.
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if <code>fn</code> is not a function.
Returns **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** The timer id.
**Meta**
* **since**: 1.0.0
### Logic
Propositional logic connectives
#### and
Creates a function that tests if all the given functions return a truthy value.
The parameters you pass when invoking the created function will be passed down to the given functions
with the this binding of the respective function.
##### Parameters
* `fns` **...[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The functions to test.
##### Examples
```javascript
and(isString, isPrimitive)("abc"); // => true
and(isString, isPrimitive)(new String("abc")); // => false
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if any of the given values is not a function, null or undefined.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that tests if all the given functions return a truthy value.
**Meta**
* **since**: 1.0.0
#### or
Creates a function that tests if any of the given functions return a truthy value.
The parameters you pass when invoking the created function will be passed down to the given functions
with the this binding of the respective function.
##### Parameters
* `fns` **...[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The functions to test.
##### Examples
```javascript
or(isString, isNumber)("abc"); // => true
or(isString, isNumber)(true); // => false
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if any of the given values is not a function, null or undefined.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that tests if any of the functions return a truthy value.
**Meta**
* **since**: 1.0.0
#### xor
Creates a function that tests if exactly one of the given functions returns a truthy value.
The parameters you pass when invoking the created function will be passed down to the given functions
with the this binding of the respective function.
##### Parameters
* `fns` **...[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The functions to test.
##### Examples
```javascript
xor(isString, isNumber)("abc"); // => true
xor(isString, isNumber)(1); // => true
xor(isString, isNumber)(true); // => false
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if any of the given values is not a function, null or undefined.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that tests if exactly one of the given functions return a truthy value.
**Meta**
* **since**: 1.0.0
#### nor
Creates a function that tests if all the given functions return a falsy value.
The parameters you pass when invoking the created function will be passed down to the given functions
with the this binding of the respective function.
##### Parameters
* `fns` **...[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The functions to test.
##### Examples
```javascript
nor(isString, isNumber)(true); // => true
nor(isString, isNumber)("abc"); // => false
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if any of the given values is not a function, null or undefined.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that tests if all the given functions return a falsy value.
**Meta**
* **since**: 1.0.0
#### not
Creates a function that negates the result of the given function.
The parameters you pass when invoking the created function will be passed down to the given function
with the this binding of the given function.
##### Parameters
* `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The function to negate.
##### Examples
```javascript
not(isString)(1); // => true
not(isString)("abc"); // => false
```
* Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** if the given value is not a function.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The new function that negates the result of the given function.
**Meta**
* **since**: 1.0.0