funcs-js
Version:
Function wrappers for enhanced behavior.
176 lines (137 loc) • 6.17 kB
Markdown
# funcs-js
[](https://www.npmjs.org/package/funcs-js) [](https://github.com/sagiegurari/funcs-js/actions) [](https://coveralls.io/r/sagiegurari/funcs-js) [](https://snyk.io/test/github/sagiegurari/funcs-js) [](http://inch-ci.org/github/sagiegurari/funcs-js) [](https://github.com/sagiegurari/funcs-js/blob/master/LICENSE) [](https://www.npmjs.org/package/funcs-js)
> Function wrappers for enhanced behavior.
* [Overview](#overview)
* [Usage](#usage)
* [once](#usage-once)
* [maxTimes](#usage-maxTimes)
* [async](#usage-async)
* [delay](#usage-delay)
* [isFunction](#usage-isFunction)
* [noop](#usage-noop)
* [ensure](#usage-ensure)
* [Installation](#installation)
* [API Documentation](docs/api.md)
* [Contributing](.github/CONTRIBUTING.md)
* [Release History](#history)
* [License](#license)
<a name="overview"></a>
## Overview
The funcs-js provides different utility functions which enable to wrap functions and modify their behavior.
This library requires no external dependencies, and it is supported for both browser and node.js environments.
<a name="usage"></a>
## Usage
In order to use the library in browser, you first must add the relevant dependency:
```html
<script type="text/javascript" src="funcs.js"></script>
```
When using an AMD loader (such as RequireJS) or CommonJS type loader, the funcs object is not automatically defined on the window scope.
For node.js, simply require the module as follows:
````js
var funcs = require('funcs-js');
````
<a name="usage-once"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.once(fn, [options]) ⇒ function'
Ensures the provided function is invoked only once.<br>
This is the same as calling funcs.maxTimes(fn, 1)<br>
This function output can be chained with other funcs apis.
**Example**
````js
const onlyOnceCallback = funcs.once(callback);
//can also chain multiple modifications (chained functions do not require original function as argument)
const asyncOnceCallback = funcs.once(callback).async();
````
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="usage-maxTimes"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.maxTimes(fn, times, [options]) ⇒ function'
Wraps the provided function and ensures it is invoked no more than the provided amount.<br>
This function output can be chained with other funcs apis.
**Example**
````js
const onlyOnceCallback = funcs.maxTimes(callback, 1);
//can also chain multiple modifications (chained functions do not require original function as argument)
const delayedMaxTimesCallback = funcs.maxTimes(callback, 5).delay(500);
````
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="usage-async"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.async(fn, [options]) ⇒ function'
Ensures the function is invoked only in the next cycle.<br>
This is the same as calling funcs.delay(fn, 0)<br>
This function output can be chained with other funcs apis.
**Example**
````js
const asyncCallback = funcs.async(callback);
//can also chain multiple modifications (chained functions do not require original function as argument)
const asyncOnceCallback = funcs.async(callback).once();
````
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="usage-delay"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.delay(fn, [delay], [options]) ⇒ function'
Trigger the actual function only after the provided delay.<br>
This function output can be chained with other funcs apis.
**Example**
````js
const delayedCallback = funcs.delay(callback, 500);
//can also chain multiple modifications (chained functions do not require original function as argument)
const delayedMaxTimesCallback = funcs.delay(callback, 500).maxTimes(5);
````
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="usage-isFunction"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.isFunction([fn]) ⇒ Boolean'
Returns true if the provided argument is a function.
**Example**
````js
const isFn = funcs.isFunction(myFunction);
funcs.isFunction(function () {}); //true
funcs.isFunction(); //false
funcs.isFunction(5); //false
funcs.isFunction(true); //false
````
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="usage-noop"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.noop() ⇒ undefined'
Empty function.
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="usage-ensure"></a>
<!-- markdownlint-disable MD009 MD031 MD036 -->
### 'funcs.ensure([fn]) ⇒ function'
Ensures a return function.<br>
If a function is provided, it will be returned, otherwise a noop function will be returned.
**Example**
````js
const handler = funcs.ensure(maybeHandler);
````
<!-- markdownlint-enable MD009 MD031 MD036 -->
<a name="installation"></a>
## Installation
Run npm install in your project as follows:
```sh
npm install --save funcs-js
```
Or if you are using bower, you can install it as follows:
```sh
bower install funcs-js --save
```
## API Documentation
See full docs at: [API Docs](docs/api.md)
## Contributing
See [contributing guide](.github/CONTRIBUTING.md)
<a name="history"></a>
## Release History
| Date | Version | Description |
| ----------- | ------- | ----------- |
| 2020-05-12 | v2.0.0 | Migrate to github actions, upgrade minimal node version and remove bower |
| 2019-02-08 | v1.0.18 | Maintenance |
| 2017-04-28 | v1.0.1 | Offical release |
| 2017-04-28 | v0.0.6 | Docs |
| 2017-04-28 | v0.0.5 | Rename package as funcs-js |
| 2017-04-27 | v0.0.1 | Initial release |
<a name="license"></a>
## License
Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.