AveAzul.js

AveAzul ("Blue Bird" in Spanish) serves as a near drop-in replacement for Bluebird. It's built on native Promise, by extending it with the familiar utility methods from Bluebird.

Purpose

The primary goal is to help migrate legacy code, that uses Bluebird APIs extensively, to native Promises. While not a 100% drop-in replacement (some aspects of Bluebird simply can't be replicated), it offers a practical migration path with minimal changes for most cases.

Further, if you like Bluebird's API but want to use native Promises, AveAzul gives you both - familiar Bluebird methods built on native Promise.

Features

• Built on native Promises
• Implements most commonly used Bluebird methods
• Comprehensive test suite ensuring compatibility

Requirements

• node.js version >= 12

Installation

1npm install aveazul

Usage

1const AveAzul = require("aveazul");
2
3// Basic Promise usage
4const promise = new AveAzul((resolve) => resolve(42));
5promise.then((value) => console.log(value)); // 42
6
7// Utility methods
8AveAzul.resolve([1, 2, 3])
9  .map((x) => x * 2)
10  .filter((x) => x > 2)
11  .then((result) => console.log(result)); // [4, 6]
12
13// Wait for at least 2 promises to be fulfilled
14const fetchUrls = [
15  fetch("https://api.example.com/data1"),
16  fetch("https://api.example.com/data2"),
17  fetch("https://api.example.com/data3"),
18  fetch("https://api.example.com/data4"),
19];
20AveAzul.some(fetchUrls, 2).then((results) =>
21  console.log(`Got the first 2 successful results`)
22);
23
24// Process items sequentially with mapSeries
25AveAzul.resolve([1, 2, 3])
26  .mapSeries(async (x) => {
27    // Each item is processed only after the previous one completes
28    await new Promise((resolve) => setTimeout(resolve, 100));
29    return x * 2;
30  })
31  .then((result) => console.log(result)); // [2, 4, 6]
32
33// Promisify callback-style functions
34const fs = require("fs");
35const readFile = AveAzul.promisify(fs.readFile);
36readFile("file.txt").then((content) => console.log(content));
37// Properties from the original function are preserved
38console.log(readFile.length); // Original function's length property
39
40// Promisify all methods of an object
41const obj = {
42  method(cb) {
43    cb(null, "result");
44  },
45};
46AveAzul.promisifyAll(obj);
47obj.methodAsync().then((result) => console.log(result)); // 'result'
48
49// Resource management with disposer and using
50const getResource = () => {
51  return AveAzul.resolve({
52    data: "important data",
53    close: () => console.log("Resource closed!"),
54  }).disposer((resource) => resource.close());
55};
56
57AveAzul.using(getResource(), (resource) => {
58  console.log(resource.data); // "important data"
59  return AveAzul.resolve("operation completed");
60}).then((result) => {
61  console.log(result); // "operation completed"
62  // Resource is automatically closed here, even if an error occurred
63});
64
65// Using spread to apply array results as arguments
66AveAzul.all([getUser(1), getPosts(1), getComments(1)]).spread(
67  (user, posts, comments) => {
68    // Instead of using .then(([user, posts, comments]) => {...})
69    console.log(
70      `User ${user.name} has ${posts.length} posts and ${comments.length} comments`
71    );
72    return { user, activity: { posts, comments } };
73  }
74);

Migration from Bluebird

For most applications, migrating from Bluebird to AveAzul should be as simple as:

1// From
2const Promise = require("bluebird");
3
4// To
5const Promise = require("aveazul");

Key differences to be aware of:

• Some advanced debugging features are not available
• Performance characteristics may differ
• A few very specialized methods not available

API

Instance Methods

• tap(fn) - Execute side effects and return original value
• filter(fn) - Filter array elements
• map(fn) - Transform array elements
• mapSeries(fn) - Transform array elements sequentially
• return(value) - Inject a new value
• each(fn) - Iterate over array elements
• delay(ms) - Delay resolution
• timeout(ms, message?) - Reject after specified time
• props(obj) - Resolve object properties
• spread(fn) - Apply array values as arguments to function
• tapCatch(fn) - Execute side effects on rejection
• reduce(fn, initialValue?) - Reduce array elements
• some(count) - Resolves when a specified number of promises in the array have resolved
• throw(reason) - Return rejected promise
• catchThrow(reason) - Catch and throw new error
• catchReturn(value) - Catch and return value
• get(propertyPath) - Retrieve property value
• disposer(fn) - Create a disposer for use with AveAzul.using() for resource cleanup
• any() - Resolves when any promise in the iterable resolves, rejecting if all reject
• all() - Like Promise.all(), resolves when all promises resolve, rejects if any reject
• call(propertyName, ...args) - Call a method on the resolved value with the provided arguments
• asCallback(callback, options?) - Register a Node-style callback that handles the resolution or rejection
• error(handler) - Like catch(), but only catches operational errors, letting programmer errors bubble up

Static Methods

• delay(ms, value?) - Resolve after specified time
• map(value, fn) - Transform array elements
• mapSeries(value, fn) - Transform array elements one at a time in sequence
• try(fn) - Wrap sync/async functions
• props(obj) - Resolve object properties
• defer() - Create a deferred promise
• promisify(fn, options?) - Convert callback-style functions to promises (preserves original function properties)
• fromNode(fn, options?) - Convert Node-style callback functions to promise-returning functions
• fromCallback(fn, options?) - Alias for fromNode
• each(items, fn) - Iterate over array elements
• reduce(array, fn, initialValue?) - Reduce array elements
• some(promises, count) - Wait for a specified number of promises to be fulfilled
• method(fn) - Creates a method that returns a promise resolving to the value returned by the original function
• throw(reason) - Return rejected promise
• promisifyAll(target, options?) - Convert all methods of an object/class to promises
• using(resources, fn) - Manage resources with automatic cleanup
• join(...values, handler?) - Wait for multiple promises and pass their resolved values as separate arguments to the handler function. If no handler is provided, behaves like Promise.all

Error Types

• AveAzul.OperationalError - Error type for representing expected operational errors (network failures, validation errors, etc.)

PromisifyAll Options

• suffix (default: 'Async') - Suffix to append to promisified method names
• filter - Filter function to determine which methods to promisify
• promisifier - Custom function to handle promisification
• multiArgs (default: false) - Whether to support multiple callback arguments

Development

1# Install dependencies
2npm install
3
4# Run tests
5npm test
6npm run test:watch
7npm run test:coverage
8
9# Test against Bluebird for compatibility
10npm run jest:bluebird -- test/[name].test.js

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0

Author

Joel Chen, with assistant from Cursor Claude-3.7-sonnet