aveazul 0.1.5 → 1.0.0

package/README.md

@@ -1,10 +1,18 @@
 # AveAzul
 
-AveAzul ("Blue Bird" in Spanish) is a Promise library that extends native Promises with Bluebird-like utility methods. Built on top of native Promises, it provides a familiar API for Node.js developers who are used to working with [Bluebird](https://github.com/petkaantonov/bluebird) ([npm](https://www.npmjs.com/package/bluebird)).
+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.
 
-This library helps migrate legacy code that uses Bluebird specific APIs to native Promises with minimal changes. It aims to provide a drop-in replacement that maintains compatibility while leveraging native Promises.
+## Purpose
 
-Do you prefer Bluebird's API with native Promises? AveAzul gives you both - familiar Bluebird methods built on native Promise.
+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
 
 ## Installation
 
@@ -27,6 +35,26 @@ AveAzul.resolve([1, 2, 3])
   .filter((x) => x > 2)
   .then((result) => console.log(result)); // [4, 6]
 
+// Wait for at least 2 promises to be fulfilled
+const fetchUrls = [
+  fetch("https://api.example.com/data1"),
+  fetch("https://api.example.com/data2"),
+  fetch("https://api.example.com/data3"),
+  fetch("https://api.example.com/data4"),
+];
+AveAzul.some(fetchUrls, 2).then((results) =>
+  console.log(`Got the first 2 successful results`)
+);
+
+// Process items sequentially with mapSeries
+AveAzul.resolve([1, 2, 3])
+  .mapSeries(async (x) => {
+    // Each item is processed only after the previous one completes
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    return x * 2;
+  })
+  .then((result) => console.log(result)); // [2, 4, 6]
+
 // Promisify callback-style functions
 const fs = require("fs");
 const readFile = AveAzul.promisify(fs.readFile);
@@ -71,6 +99,24 @@ AveAzul.all([getUser(1), getPosts(1), getComments(1)]).spread(
 );
 ```
 
+## Migration from Bluebird
+
+For most applications, migrating from Bluebird to AveAzul should be as simple as:
+
+```javascript
+// From
+const Promise = require("bluebird");
+
+// To
+const 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
@@ -78,6 +124,7 @@ AveAzul.all([getUser(1), getPosts(1), getComments(1)]).spread(
 - `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
@@ -86,16 +133,22 @@ AveAzul.all([getUser(1), getPosts(1), getComments(1)]).spread(
 - `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
 
 ### 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
@@ -104,6 +157,7 @@ AveAzul.all([getUser(1), getPosts(1), getComments(1)]).spread(
 - `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
@@ -127,12 +181,19 @@ npm install
 npm test
 npm run test:watch
 npm run test:coverage
+
+# Test against Bluebird for compatibility
+npm 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
+Joel Chen, with assistant from Cursor Claude-3.7-sonnet

package/lib/aveazul.js

@@ -8,7 +8,8 @@ const { using } = require("./using");
 const { isPromise, triggerUncaughtException } = require("./util");
 
 /**
- * AveAzul ("Blue Bird" in Spanish) - Extended Promise class that provides Bluebird-like utility methods
+ * @fileoverview
+ * AveAzul ("Blue Bird" in Spanish) - Extended Promise class that provides Bluebird like utility methods
  * This implementation is inspired by and provides similar APIs to the Bluebird Promise library,
  * but built on top of native Promises. The name is a Spanish play on words referencing Bluebird.
  * @extends Promise
@@ -54,8 +55,18 @@ class AveAzul extends Promise {
    * @param {Function} fn - Map function to apply to each element
    * @returns {Promise} Promise that resolves with the mapped array
    */
-  map(fn) {
-    return this.then((value) => xaa.map(value, fn));
+  map(fn, options = { concurrency: 50 }) {
+    return this.then((value) => xaa.map(value, fn, options));
+  }
+
+  /**
+   * Bluebird-style mapSeries() method for array operations
+   * Similar to Bluebird's Promise.prototype.mapSeries()
+   * @param {Function} fn - Map function to apply to each element
+   * @returns {Promise} Promise that resolves with the mapped array
+   */
+  mapSeries(fn) {
+    return this.map(fn, { concurrency: 1 });
   }
 
   /**
@@ -68,6 +79,30 @@ class AveAzul extends Promise {
     return this.then(() => value);
   }
 
+  /**
+   * Bluebird-style any() method for waiting for any promises to resolve
+   * @param {Array|Iterable} promises - Array or iterable of promises
+   * @returns {Promise} Promise that resolves with the first resolved promise
+   */
+  any() {
+    return this.then((args) => {
+      if (!Array.isArray(args)) {
+        // Check if args is iterable
+        if (args != null && typeof args[Symbol.iterator] === "function") {
+          // Convert iterable to array, must do this to get the length, in order
+          // to detect if too many errors occurred and completion is impossible.
+          args = Array.from(args);
+        } else {
+          throw new TypeError(
+            "expecting an array or an iterable object but got " + args
+          );
+        }
+      }
+
+      return AveAzul.any(args);
+    });
+  }
+
   /**
    * Bluebird-style each() method for array iteration
    * Similar to Bluebird's Promise.prototype.each()
@@ -253,6 +288,138 @@ class AveAzul extends Promise {
       }
     });
   }
+
+  some(count) {
+    return this.then((args) => {
+      if (!Array.isArray(args)) {
+        // Check if args is iterable
+        if (args != null && typeof args[Symbol.iterator] === "function") {
+          // Convert iterable to array, must do this to get the length, in order
+          // to detect if too many errors occurred and completion is impossible.
+          args = Array.from(args);
+        } else {
+          throw new TypeError(
+            "expecting an array or an iterable object but got " + args
+          );
+        }
+      }
+
+      return new AveAzul((resolve, reject) => {
+        // If too many promises are rejected so that the promise can never become fulfilled,
+        // it will be immediately rejected with an AggregateError of the rejection reasons
+        // in the order they were thrown in.
+        const errors = [];
+        // The fulfillment value is an array with count values
+        // in the order they were fulfilled.
+        const results = [];
+        const len = args.length;
+
+        const addDone = (result) => {
+          results.push(result);
+          if (results.length >= count) {
+            // Resolve with exactly count results to match Bluebird's behavior
+            resolve(results.slice(0, count));
+          }
+        };
+
+        const addError = (err) => {
+          errors.push(err);
+          if (len - errors.length < count) {
+            reject(new AggregateError(errors, `aggregate error`));
+          }
+        };
+
+        for (let i = 0; i < len; i++) {
+          const x = args[i];
+          if (isPromise(x)) {
+            x.then(addDone, addError);
+          } else {
+            addDone(x);
+          }
+        }
+      });
+    });
+  }
+
+  /**
+   * Bluebird-style all() method for array operations
+   * Similar to Promise.all() but operates on the resolved value of this promise
+   * @returns {Promise} Promise that resolves when all items in the array resolve
+   */
+  all() {
+    return this.then((value) => {
+      if (!Array.isArray(value)) {
+        // Check if value is iterable
+        if (value != null && typeof value[Symbol.iterator] === "function") {
+          // Convert iterable to array
+          value = Array.from(value);
+        } else {
+          throw new TypeError(
+            "expecting an array or an iterable object but got " + value
+          );
+        }
+      }
+
+      return AveAzul.all(value);
+    });
+  }
+
+  /**
+   * Bluebird-style asCallback() method
+   * Attaches a callback to the promise and returns the promise.
+   * The callback is invoked when the promise is resolved or rejected.
+   *
+   * @param {Function} cb - Node.js-style callback function (err, value)
+   * @param {Object} [options] - Additional options
+   * @param {boolean} [options.spread=false] - Pass array values as arguments to callback
+   * @returns {Promise} The same promise instance
+   */
+  asCallback(cb, options = {}) {
+    if (typeof cb !== "function") {
+      return this;
+    }
+
+    const spread = options && options.spread === true;
+
+    this.then(
+      (value) => {
+        try {
+          if (spread && Array.isArray(value)) {
+            cb(null, ...value);
+          } else {
+            cb(null, value);
+          }
+        } catch (err) {
+          AveAzul.___throwUncaughtError(err);
+        }
+      },
+      (reason) => {
+        try {
+          cb(reason);
+        } catch (err) {
+          AveAzul.___throwUncaughtError(err);
+        }
+      }
+    );
+
+    return this;
+  }
+
+  nodeify(cb, options) {
+    return this.asCallback(cb, options);
+  }
+
+  /**
+   * Bluebird-style call() method for calling a method on the resolved value
+   * @param {string} methodName - Name of the method to call
+   * @param {...any} args - Arguments to pass to the method
+   * @returns {Promise} Promise that resolves with the method's return value
+   */
+  call(methodName, ...args) {
+    return this.then(function (obj) {
+      return obj[methodName].call(obj, ...args);
+    });
+  }
 }
 
 /**
@@ -278,7 +445,16 @@ AveAzul.delay = (ms, value) => {
  * @param {Function} fn - Map function to apply to each element
  * @returns {Promise} Promise that resolves with the mapped array
  */
-AveAzul.map = (value, fn) => AveAzul.resolve(xaa.map(value, fn));
+AveAzul.map = (value, fn, options = { concurrency: 50 }) =>
+  AveAzul.resolve(value).map(fn, options);
+
+/**
+ * Bluebird-style mapSeries() for array operations
+ * @param {Array} value - Array to map over
+ * @param {Function} fn - Map function to apply to each element
+ * @returns {Promise} Promise that resolves with the mapped array
+ */
+AveAzul.mapSeries = (value, fn) => AveAzul.map(value, fn, { concurrency: 1 });
 
 /**
  * Bluebird-style try() for wrapping sync/async functions
@@ -455,7 +631,18 @@ AveAzul.fromCallback = fromCallback;
  */
 AveAzul.___throwUncaughtError = triggerUncaughtException;
 
-module.exports = AveAzul;
+/**
+ * Bluebird-style some() for waiting for some promises to resolve
+ * @param {Array|Iterable} promises - Array or iterable of promises
+ * @param {number} count - Number of promises that need to resolve
+ * @returns {Promise} Promise that resolves when count promises have resolved
+ */
+AveAzul.some = function (promises, count) {
+  return AveAzul.resolve(promises).some(count);
+};
 
+// Setup the not implemented methods
 const { setupNotImplemented } = require("./not-implemented");
 setupNotImplemented(AveAzul);
+
+module.exports = AveAzul;

package/lib/not-implemented.js

@@ -10,17 +10,19 @@ function createNotImplemented(name) {
 
 function createInstanceNotImplemented(AveAzul) {
   const methods = [
+    "then",
     "spread",
+    "catch",
     "error",
+    "finally",
     "bind",
-    "join",
-    "try",
-    "method",
     "isFulfilled",
     "isRejected",
     "isPending",
+    "isCancelled",
     "value",
     "reason",
+    "all",
     "props",
     "any",
     "some",
@@ -29,13 +31,22 @@ function createInstanceNotImplemented(AveAzul) {
     "filter",
     "each",
     "mapSeries",
+    "disposer",
+    "asCallback",
+    "delay",
+    "timeout",
+    "cancel",
     "tap",
     "tapCatch",
-    "catchThrow",
-    "catchReturn",
+    "call",
     "get",
+    "return",
     "throw",
-    "call",
+    "catchReturn",
+    "catchThrow",
+    "reflect",
+    "suppressUnhandledRejections",
+    "done",
   ];
 
   const proto = AveAzul.prototype;
@@ -56,22 +67,25 @@ function createStaticNotImplemented(AveAzul) {
     "method",
     "resolve",
     "reject",
-    "all",
     "props",
     "any",
     "some",
     "map",
+    "reduce",
     "filter",
     "each",
     "mapSeries",
     "race",
+    "using",
     "promisify",
     "promisifyAll",
-    "fromNode",
     "fromCallback",
     "delay",
     "coroutine",
-    "config",
+    "coroutine.addYieldHandler",
+    "getNewLibraryCopy",
+    "noConflict",
+    "setScheduler",
   ];
   const ret = [];
   for (const method of methods) {
@@ -84,9 +98,9 @@ function createStaticNotImplemented(AveAzul) {
 }
 
 function setupNotImplemented(AveAzul) {
-  const instance = createInstanceNotImplemented(AveAzul);
+  const instanceMethods = createInstanceNotImplemented(AveAzul);
   const staticMethods = createStaticNotImplemented(AveAzul);
-  AveAzul.__notImplementedInstance = instance;
+  AveAzul.__notImplementedInstance = instanceMethods;
   AveAzul.__notImplementedStatic = staticMethods;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aveazul",
-  "version": "0.1.5",
-  "description": "Bluebird-like APIs in extended native Promise",
+  "version": "1.0.0",
+  "description": "Bluebird drop-in replacement built on native Promise",
   "main": "lib/aveazul.js",
   "homepage": "https://github.com/jchip/aveazul",
   "license": "Apache-2.0",
@@ -16,6 +16,9 @@
     "jest:bluebird": "USE_BLUEBIRD=true jest --no-coverage"
   },
   "author": "Joel Chen",
+  "contributors": [
+    "Claude (AI assistant)"
+  ],
   "files": [
     "lib"
   ],
@@ -23,7 +26,34 @@
     "promise",
     "async",
     "bluebird",
-    "nodejs"
+    "nodejs",
+    "node.js",
+    "promises",
+    "promise-library",
+    "native-promise",
+    "es6-promise",
+    "migration",
+    "promisify",
+    "utility",
+    "using",
+    "disposer",
+    "spread",
+    "promise-map",
+    "async-map",
+    "p-map",
+    "map-series",
+    "async-await",
+    "promise-chain",
+    "promise-utils",
+    "asynchronous",
+    "callback",
+    "promisifyall",
+    "timeout",
+    "delay",
+    "any",
+    "props",
+    "filter",
+    "reduce"
   ],
   "repository": {
     "type": "git",