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.

npm install villa --save

Usage Example

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

[+] awaitable<T>(target: any, ...args: any[]): Promise<T>

Create a promise for an object.

[+] chainable<T>(resolvable: Resolvable<T[]>): Chainable<T>

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

[+] lock<T>(object: any, handler: LockHandler<T>): Promise<T>

A simple asynchronous lock that helps queueing operations.

[+] parallel<T>(values: T[], handler: ParallelHandler<T>, concurrency?: number): Promise<void>

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

[+] race<T, TResult>(values: T[], transformer: RaceTransformer<T, TResult>): Promise<TResult>

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

[+] call<T>(fn: NodeStyleAsyncFunction<T>, ...args: any[]): Promise<T>

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

[+] async<T>(fn: NodeStyleAsyncFunction<T>): AsyncFunction<T>

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

[+] bear(_error: any): undefined

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

[+] sleep(duration: number): Promise<void>

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

[+] retry<T>(handler: RetryHandler<T>, options?: RetryOptions): Promise<T>

Retry procedure in the handler for several times.

[+] each<T>(values: T[], handler: EachHandler<T>): Promise<boolean>

Asynchronous version of Array#forEach().

[+] some<T>(values: T[], handler: SomeHandler<T>): Promise<boolean>

Asynchronous version of Array#some().

[+] every<T>(values: T[], handler: EveryHandler<T>): Promise<boolean>

Asynchronous version of Array#every().

[+] map<T, TResult>(values: T[], transformer: MapTransformer<T, TResult>, concurrency?: number): Promise<TResult[]>

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

[+] reduce<T, TResult>(values: T[], transformer: ReduceTransformer<T, TResult>, initial: TResult): Promise<TResult>⁺¹

Asynchronous version of Array#reduce().

Overloads:

• reduce<T>(values: T[], transformer: ReduceTransformer<T, T>): Promise<T | undefined>

[+] reduceRight<T, TResult>(values: T[], transformer: ReduceTransformer<T, TResult>, initial: TResult): Promise<TResult>⁺¹

Asynchronous version of Array#reduceRight().

Overloads:

• reduceRight<T>(values: T[], transformer: ReduceTransformer<T, T>): Promise<T | undefined>

[+] filter<T>(values: T[], handler: FilterHandler<T>): Promise<T[]>

Asynchronous version of Array#filter().

[+] find<T>(values: T[], handler: FindHandler<T>): Promise<T | undefined>

Asynchronous version of Array#find().

[+] findIndex<T>(values: T[], handler: FindHandler<T>): Promise<number>

Asynchronous version of Array#findIndex().

License

MIT License.