Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vilicvane/villa

🏡 Villa is a set of promise utilities for async-await-ready environment.
https://github.com/vilicvane/villa

Last synced: 20 days ago
JSON representation

🏡 Villa is a set of promise utilities for async-await-ready environment.

Awesome Lists containing this project

README 

        
[![NPM Package](https://badge.fury.io/js/villa.svg)](https://www.npmjs.com/package/villa)

[![Build Status](https://travis-ci.org/vilic/villa.svg)](https://travis-ci.org/vilic/villa)

[![Coverage Status](https://coveralls.io/repos/github/vilic/villa/badge.svg?branch=master)](https://coveralls.io/github/vilic/villa?branch=master)



# Villa



Villa is a set of promise utilities for `async`-`await`-ready environment.



Promises have been widely used in JavaScript, and there are quite a few fully

featured promise libraries like

[bluebird](https://github.com/petkaantonov/bluebird) and

[Q](https://github.com/kriskowal/q). But with the growing adoption of

`async`/`await` provided by ES-next (via transpilers like

[TypeScript](http://www.typescriptlang.org/) and [Babel](http://babeljs.io/)),

some critical features provided by those libraries become less relevant.



And there is another problem with third-party promise for code using

`async`/`await`: it could be confusing having different promise instances with

different APIs, while an `async` function always returns native promise object.



While most of the promise use cases so far can be addressed using

`async`/`await` with simple helpers, I created villa with my favorite features

from my own promise library [ThenFail](https://github.com/vilic/thenfail) and

more.



## Installation



Villa is written in TypeScript and compiled with TypeScript 2.0, and works with

TypeScript, Babel and ES6 generators.



```sh

npm install villa --save

```



## Usage Example

```ts

import * as FS from 'fs';

import * as Path from 'path';



import * as v from 'villa';



// Add support for Node.js specific features, e.g. awaitable for Node.js objects.

import 'villa/platform/node';



async function copy(source, target) {

    let readStream = FS.createReadStream(source);

    let writeStream = FS.createWriteStream(target);



    readStream.pipe(writeStream);



    await v.awaitable(writeStream, [readStream]);

}



async function copyAll(sourceDir, targetDir) {

    await v

        .chainable(v.call(FS.readdir, sourceDir))

        .filter(async fileName => {

            let stats = await v.call(FS.stat, fileName);

            return stats.isFile();

        })

        .each(async fileName => {

            let source = Path.join(sourceDir, fileName);

            let target = Path.join(targetDir, fileName);

            await copy(source, target);

        });

}

```



## API References



#### [[+]](src/awaitable.ts#L17) `awaitable(target: any, ...args: any[]): Promise`



Create a promise for an object.



#### [[+]](src/chainable.ts#L124) `chainable(resolvable: Resolvable): Chainable`



Wrap given resolvable with a chainable derived of built-in promise.



#### [[+]](src/concurrency.ts#L18) `lock(object: any, handler: LockHandler): Promise`



A simple asynchronous lock that helps queueing operations.



#### [[+]](src/concurrency.ts#L36) `parallel(values: T[], handler: ParallelHandler, concurrency?: number): Promise`



Run tasks in parallel, similar to `v.map` but not mean to transform.



#### [[+]](src/concurrency.ts#L53) `race(values: T[], transformer: RaceTransformer): Promise`



Race tasks and fulfill or reject as soon as one of them fulfills or rejects.



#### [[+]](src/function.ts#L21) `call(fn: NodeStyleAsyncFunction, ...args: any[]): Promise`



Call a Node.js-style asynchronous function and return a correspondent

promise.



#### [[+]](src/function.ts#L42) `async(fn: NodeStyleAsyncFunction): AsyncFunction`



Wrap a Node.js-style asynchronous function to a function that returns

promise.



#### [[+]](src/miscellaneous.ts#L6) `bear(_error: any): undefined`



A no-operation function that acts as the rejection handler of a promise.



#### [[+]](src/miscellaneous.ts#L14) `sleep(duration: number): Promise`



Create a promise that will be fulfilled in given duration (milliseconds).



#### [[+]](src/miscellaneous.ts#L36) `retry(handler: RetryHandler, options?: RetryOptions): Promise`



Retry procedure in the handler for several times.



#### [[+]](src/array.ts#L12) `each(values: T[], handler: EachHandler): Promise`



Asynchronous version of `Array#forEach()`.



#### [[+]](src/array.ts#L34) `some(values: T[], handler: SomeHandler): Promise`



Asynchronous version of `Array#some()`.



#### [[+]](src/array.ts#L56) `every(values: T[], handler: EveryHandler): Promise`



Asynchronous version of `Array#every()`.



#### [[+]](src/array.ts#L78) `map(values: T[], transformer: MapTransformer, concurrency?: number): Promise`



Asynchronous version of `Array#map()` with basic concurrency control.



#### [[+]](src/array.ts#L150) `reduce(values: T[], transformer: ReduceTransformer, initial: TResult): Promise`+1



Asynchronous version of `Array#reduce()`.



##### Overloads:



- `reduce(values: T[], transformer: ReduceTransformer): Promise`



#### [[+]](src/array.ts#L175) `reduceRight(values: T[], transformer: ReduceTransformer, initial: TResult): Promise`+1



Asynchronous version of `Array#reduceRight()`.



##### Overloads:



- `reduceRight(values: T[], transformer: ReduceTransformer): Promise`



#### [[+]](src/array.ts#L206) `filter(values: T[], handler: FilterHandler): Promise`



Asynchronous version of `Array#filter()`.



#### [[+]](src/array.ts#L231) `find(values: T[], handler: FindHandler): Promise`



Asynchronous version of `Array#find()`.



#### [[+]](src/array.ts#L248) `findIndex(values: T[], handler: FindHandler): Promise`



Asynchronous version of `Array#findIndex()`.



## License



MIT License.