aveazul 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2025 Joel Chen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License. 

package/README.md

@@ -0,0 +1,87 @@
+# AveAzul
+
+AveAzul ("Blue Bird" in Spanish) is a Promise extension library that provides Bluebird-like utility methods built on top of native Promises. The name is a Spanish play on words referencing Bluebird.
+
+## Requirements
+
+- Node.js 16 or higher
+
+## Features
+
+- Extends native Promise with Bluebird-like utility methods
+- Built on top of the efficient `xaa` library for async operations
+- Zero external runtime dependencies (other than `xaa`)
+- TypeScript-friendly
+- Familiar Bluebird-style API
+
+## Installation
+
+```bash
+npm install aveazul
+```
+
+## Usage
+
+```javascript
+const AveAzul = require('aveazul');
+
+// Create a new promise
+const promise = new AveAzul((resolve, reject) => {
+  setTimeout(() => resolve('result'), 1000);
+});
+
+// Use Bluebird-style methods
+promise
+  .tap(value => console.log('Got:', value))
+  .delay(500)
+  .then(value => console.log('After delay:', value));
+
+// Static helpers
+AveAzul.delay(1000, 'hello')
+  .then(value => console.log(value));
+
+// Array operations
+AveAzul.resolve([1, 2, 3])
+  .map(x => x * 2)
+  .filter(x => x > 4)
+  .then(result => console.log(result)); // [6]
+```
+
+## API
+
+### Instance Methods
+
+- `tap(fn)` - Execute side effects in a chain
+- `filter(fn)` - Filter array elements
+- `map(fn)` - Map array elements
+- `return(value)` - Inject a value into the chain
+- `each(fn)` - Iterate over array elements
+- `delay(ms)` - Delay execution
+- `timeout(ms, message?)` - Set operation timeout
+- `try(fn)` - Wrap sync/async functions
+- `props(obj)` - Handle object properties
+- `reduce(fn, initialValue?)` - Reduce array
+- `throw(reason)` - Return rejected promise
+- `catchThrow(reason)` - Catch and throw new error
+- `catchReturn(value)` - Catch and return value
+- `get(propertyPath)` - Get nested property
+
+### Static Methods
+
+- `AveAzul.delay(ms, value?)` - Create delayed promise
+- `AveAzul.map(array, fn)` - Map array elements
+- `AveAzul.try(fn)` - Wrap function execution
+- `AveAzul.props(obj)` - Handle object properties
+- `AveAzul.defer()` - Create deferred promise
+- `AveAzul.promisify(fn, options?)` - Promisify callback functions
+- `AveAzul.each(items, fn)` - Iterate over items
+- `AveAzul.reduce(array, fn, initialValue?)` - Reduce array
+- `AveAzul.throw(reason)` - Create rejected promise
+
+## License
+
+Apache 2.0
+
+## Dependencies
+
+- [xaa](https://github.com/jchip/xaa) - Efficient async/await helpers

package/lib/aveazul.js

@@ -0,0 +1,356 @@
+"use strict";
+
+const xaa = require("xaa");
+const { promisify: nodePromisify } = require("node:util");
+
+/**
+ * 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
+ */
+class AveAzul extends Promise {
+  constructor(executor) {
+    super(executor);
+  }
+
+  /**
+   * Note: Per ECMAScript specification, when extending Promise, both .then() and static methods
+   * (resolve, reject, all, etc) must return instances of the derived class (AveAzul), so there's
+   * no need to explicitly wrap returns in new AveAzul(). This behavior is standard across all
+   * spec-compliant JS engines (V8, SpiderMonkey, JavaScriptCore, etc).
+   */
+
+  /**
+   * Bluebird-style tap() method that lets you perform side effects in a chain
+   * Similar to Bluebird's Promise.prototype.tap()
+   * @param {Function} fn - Function to execute with the resolved value
+   * @returns {Promise} Promise that resolves with the original value
+   */
+  tap(fn) {
+    return this.then(value => {
+      fn(value);
+      return value;
+    });
+  }
+
+  /**
+   * Bluebird-style filter() method for array operations
+   * Similar to Bluebird's Promise.prototype.filter()
+   * @param {Function} fn - Filter function to apply to each element
+   * @returns {Promise} Promise that resolves with the filtered array
+   */
+  filter(fn) {
+    return this.then(value => xaa.filter(value, fn));
+  }
+
+  /**
+   * Bluebird-style map() method for array operations
+   * Similar to Bluebird's Promise.prototype.map()
+   * @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));
+  }
+
+  /**
+   * Bluebird-style return() method to inject a value into the chain
+   * Similar to Bluebird's Promise.prototype.return()
+   * @param {*} value - Value to return
+   * @returns {Promise} Promise that resolves with the new value
+   */
+  return(value) {
+    return this.then(() => value);
+  }
+
+  /**
+   * Bluebird-style each() method for array iteration
+   * Similar to Bluebird's Promise.prototype.each()
+   * @param {Function} fn - Function to execute for each element
+   * @returns {Promise} Promise that resolves when iteration is complete
+   */
+  each(fn) {
+    return this.then(value => xaa.each(value, fn));
+  }
+
+  /**
+   * Bluebird-style delay() method
+   * @param {number} ms - Milliseconds to delay
+   * @returns {Promise} Promise that resolves after the delay
+   */
+  delay(ms) {
+    return this.then(value => xaa.delay(ms, value));
+  }
+
+  /**
+   * Bluebird-style timeout() method
+   * @param {number} ms - Milliseconds before timeout
+   * @param {string} [message] - Optional error message
+   * @returns {Promise} Promise that rejects if timeout occurs
+   */
+  timeout(ms, message = "Operation timed out") {
+    return new AveAzul((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(message));
+      }, ms);
+
+      this.then(
+        value => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        err => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+
+  /**
+   * Bluebird-style try() for wrapping sync/async functions
+   * @param {Function} fn - Function to execute
+   * @returns {Promise} Promise that resolves with the function's return value
+   */
+  try(fn) {
+    return new AveAzul((resolve, reject) => {
+      try {
+        const result = fn();
+        if (result && typeof result.then === "function") {
+          result.then(resolve, reject);
+        } else {
+          resolve(result);
+        }
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Bluebird-style props() for object properties
+   * @param {Object} obj - Object with promise values
+   * @returns {Promise} Promise that resolves with an object of resolved values
+   */
+  props(obj) {
+    const keys = Object.keys(obj);
+    const values = keys.map(k => obj[k]);
+
+    return AveAzul.all(values).then(results => {
+      const resolved = {};
+      keys.forEach((k, i) => {
+        resolved[k] = results[i];
+      });
+      return resolved;
+    });
+  }
+
+  /**
+   * Bluebird-style catchIf() with predicate matching
+   * @param {Function|Error} predicate - Error class or predicate function
+   * @param {Function} fn - Handler function
+   * @returns {Promise} Promise with conditional catch handler
+   */
+  catchIf(predicate, fn) {
+    return this.catch(err => {
+      if (
+        (typeof predicate === "function" && !predicate.prototype && predicate(err)) ||
+        (typeof predicate === "function" && predicate.prototype && err instanceof predicate)
+      ) {
+        return fn(err);
+      }
+      throw err;
+    });
+  }
+
+  /**
+   * Bluebird-style tapCatch() for side effects on rejection
+   * @param {Function} fn - Function to execute on rejection
+   * @returns {Promise} Promise that maintains the rejection
+   */
+  tapCatch(fn) {
+    return this.catch(err => {
+      fn(err);
+      throw err;
+    });
+  }
+
+  /**
+   * Bluebird-style reduce() method for array reduction
+   * Similar to Bluebird's Promise.prototype.reduce()
+   * @param {Function} fn - Reducer function to apply to each element
+   * @param {*} [initialValue] - Optional initial value
+   * @returns {Promise} Promise that resolves with the final reduced value
+   */
+  reduce(fn, initialValue) {
+    return this.then(array => AveAzul.reduce(array, fn, initialValue));
+  }
+
+  /**
+   * Bluebird-style throw() that returns a rejected promise with the given reason
+   * @param {*} reason - Value to reject the promise with
+   * @returns {Promise} Promise that rejects with the given reason
+   */
+  throw(reason) {
+    return AveAzul.reject(reason);
+  }
+
+  /**
+   * Bluebird-style catchThrow() that catches an error and throws a new one
+   * @param {*} reason - Value to reject the promise with
+   * @returns {Promise} Promise that rejects with the new reason
+   */
+  catchThrow(reason) {
+    return this.catch(() => AveAzul.throw(reason));
+  }
+
+  /**
+   * Bluebird-style catchReturn() that catches an error and returns a value instead
+   * @param {*} value - Value to return
+   * @returns {Promise} Promise that resolves with the given value
+   */
+  catchReturn(value) {
+    return this.catch(() => value);
+  }
+
+  /**
+   * Bluebird-style get() for retrieving a property value
+   * @param {string|number} propertyPath - Path to the property (can be nested using dot notation)
+   * @returns {Promise} Promise that resolves with the property value
+   */
+  get(propertyPath) {
+    return this.then(value => {
+      if (value == null) {
+        throw new TypeError("Cannot read property '" + propertyPath + "' of " + value);
+      }
+
+      let result = value;
+      const props = String(propertyPath).split(".");
+
+      for (const prop of props) {
+        if (result == null) {
+          throw new TypeError("Cannot read property '" + prop + "' of " + result);
+        }
+        result = result[prop];
+      }
+
+      return result;
+    });
+  }
+}
+
+/**
+ * Static helper methods
+ */
+
+/**
+ * Bluebird-style delay() that resolves after specified milliseconds
+ * @param {number} ms - Milliseconds to delay
+ * @param {*} [value] - Optional value to resolve with
+ * @returns {Promise} Promise that resolves after the delay
+ */
+AveAzul.delay = (ms, value) => {
+  if (value === undefined) {
+    return AveAzul.resolve(xaa.delay(ms));
+  }
+  return AveAzul.resolve(xaa.delay(ms, value));
+};
+
+/**
+ * Bluebird-style map() 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.map = (value, fn) => AveAzul.resolve(xaa.map(value, fn));
+
+/**
+ * Bluebird-style try() for wrapping sync/async functions
+ * @param {Function} fn - Function to execute
+ * @returns {Promise} Promise that resolves with the function's return value
+ */
+AveAzul.try = fn => AveAzul.resolve(xaa.wrap(fn));
+
+/**
+ * Bluebird-style props() for object properties
+ * @param {Object} obj - Object with promise values
+ * @returns {Promise} Promise that resolves with an object of resolved values
+ */
+AveAzul.props = obj => {
+  const keys = Object.keys(obj);
+  const values = keys.map(k => obj[k]);
+
+  return AveAzul.all(values).then(results => {
+    const resolved = {};
+    keys.forEach((k, i) => {
+      resolved[k] = results[i];
+    });
+    return resolved;
+  });
+};
+
+/**
+ * Bluebird-style defer() for creating a deferred promise
+ * @returns {Object} Deferred object with promise, resolve, and reject methods
+ */
+AveAzul.defer = () => {
+  const deferred = xaa.makeDefer();
+  deferred.promise = AveAzul.resolve(deferred.promise);
+  return deferred;
+};
+
+/**
+ * Bluebird-style promisify() for converting callback-style functions to promises
+ * @param {Function} fn - Function to promisify
+ * @param {Object} [options] - Options object
+ * @param {Object} [options.context] - `this` context to bind the function to
+ * @returns {Function} Promisified function that returns an AveAzul promise
+ */
+AveAzul.promisify = (fn, options = {}) => {
+  const promisified = nodePromisify(fn);
+  if (options.context) {
+    return (...args) => AveAzul.resolve(promisified.apply(options.context, args));
+  }
+  return (...args) => AveAzul.resolve(promisified(...args));
+};
+
+/**
+ * Bluebird-style each() for array iteration
+ * @param {Array} items - Array to iterate over
+ * @param {Function} fn - Iterator function to call for each item
+ * @returns {Promise} Promise that resolves when iteration is complete
+ */
+AveAzul.each = (items, fn) => AveAzul.resolve(xaa.each(items, fn));
+
+/**
+ * Bluebird-style reduce() for array reduction
+ * @param {Array} array - Array to reduce
+ * @param {Function} fn - Reducer function (value, item, index, length)
+ * @param {*} [initialValue] - Optional initial value
+ * @returns {Promise} Promise that resolves with the final reduced value
+ */
+AveAzul.reduce = (array, fn, initialValue) => {
+  const hasInitial = arguments.length > 2;
+  const len = array.length;
+
+  return AveAzul.resolve().then(async () => {
+    let value = hasInitial ? initialValue : array[0];
+    const start = hasInitial ? 0 : 1;
+
+    for (let i = start; i < len; i++) {
+      value = await fn(value, array[i], i, len);
+    }
+
+    return value;
+  });
+};
+
+/**
+ * Bluebird-style throw() that returns a rejected promise with the given reason
+ * @param {*} reason - Value to reject the promise with
+ * @returns {Promise} Promise that rejects with the given reason
+ */
+AveAzul.throw = reason => AveAzul.reject(reason);
+
+module.exports = AveAzul;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "aveazul",
+  "version": "0.1.0",
+  "description": "Extend native Promise with bluebird like APIs",
+  "main": "lib/aveazul.js",
+  "homepage": "",
+  "license": "Apache-2.0",
+  "scripts": {
+    "test": "jest test",
+    "test:watch": "jest test --watch",
+    "test:coverage": "jest test --coverage"
+  },
+  "author": "Joel Chen",
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "promise",
+    "async",
+    "bluebird",
+    "nodejs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "xaa": "^1.7.3"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}