villa
Version:
Promise utilities for async/await-ready environment.
164 lines (101 loc) • 6.66 kB
Markdown
[](https://www.npmjs.com/package/villa)
[](https://travis-ci.org/vilic/villa)
[](https://coveralls.io/github/vilic/villa?branch=master)
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
[](https://github.com/petkaantonov/bluebird) and
[](https://github.com/kriskowal/q). But with the growing adoption of
`async`/`await` provided by ES-next (via transpilers like
[](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.
Villa is written in TypeScript and compiled with TypeScript 2.0, and works with
TypeScript, Babel and ES6 generators.
```sh
npm install villa --save
```
```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);
});
}
```
<!-- docheat:functions -->
Create a promise for an object.
Wrap given resolvable with a chainable derived of built-in promise.
A simple asynchronous lock that helps queueing operations.
Run tasks in parallel, similar to `v.map` but not mean to transform.
Race tasks and fulfill or reject as soon as one of them fulfills or rejects.
Call a Node.js-style asynchronous function and return a correspondent
promise.
Wrap a Node.js-style asynchronous function to a function that returns
promise.
A no-operation function that acts as the rejection handler of a promise.
Create a promise that will be fulfilled in given duration (milliseconds).
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/miscellaneous.ts#L36) `retry<T>(handler: RetryHandler<T>, options?: RetryOptions): Promise<T>`
Retry procedure in the handler for several times.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L12) `each<T>(values: T[], handler: EachHandler<T>): Promise<boolean>`
Asynchronous version of `Array#forEach()`.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L34) `some<T>(values: T[], handler: SomeHandler<T>): Promise<boolean>`
Asynchronous version of `Array#some()`.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L56) `every<T>(values: T[], handler: EveryHandler<T>): Promise<boolean>`
Asynchronous version of `Array#every()`.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L78) `map<T, TResult>(values: T[], transformer: MapTransformer<T, TResult>, concurrency?: number): Promise<TResult[]>`
Asynchronous version of `Array#map()` with basic concurrency control.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L150) `reduce<T, TResult>(values: T[], transformer: ReduceTransformer<T, TResult>, initial: TResult): Promise<TResult>`<sup>+1</sup>
Asynchronous version of `Array#reduce()`.
##### Overloads:
- `reduce<T>(values: T[], transformer: ReduceTransformer<T, T>): Promise<T | undefined>`
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L175) `reduceRight<T, TResult>(values: T[], transformer: ReduceTransformer<T, TResult>, initial: TResult): Promise<TResult>`<sup>+1</sup>
Asynchronous version of `Array#reduceRight()`.
##### Overloads:
- `reduceRight<T>(values: T[], transformer: ReduceTransformer<T, T>): Promise<T | undefined>`
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L206) `filter<T>(values: T[], handler: FilterHandler<T>): Promise<T[]>`
Asynchronous version of `Array#filter()`.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L231) `find<T>(values: T[], handler: FindHandler<T>): Promise<T | undefined>`
Asynchronous version of `Array#find()`.
#### [[+]](https://github.com/vilic/villa/blob/v0.3.1/src/array.ts#L248) `findIndex<T>(values: T[], handler: FindHandler<T>): Promise<number>`
Asynchronous version of `Array#findIndex()`.
<!-- endcheat -->
## License
MIT License.