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 and
Q. But with the growing adoption of
async/await provided by ES-next (via transpilers like
TypeScript and Babel),
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 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⁺¹

Asynchronous version of Array#reduce().

##### Overloads:

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

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

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.