{"id":16189850,"url":"https://github.com/benjamingr/bluebird-api","last_synced_at":"2025-10-29T16:33:26.809Z","repository":{"id":57189955,"uuid":"85098113","full_name":"benjamingr/bluebird-api","owner":"benjamingr","description":"Bluebird compatible API on top of native promises.","archived":false,"fork":false,"pushed_at":"2023-10-06T14:23:21.000Z","size":218,"stargazers_count":37,"open_issues_count":7,"forks_count":17,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-01-12T13:46:45.254Z","etag":null,"topics":["bluebird","bluebird-api","native-promises","node-js","nodejs","promise","promises"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benjamingr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-15T16:51:52.000Z","updated_at":"2021-12-17T08:04:07.000Z","dependencies_parsed_at":"2024-10-27T19:35:48.191Z","dependency_job_id":"413ca668-3e97-4acd-9b68-1b7609fc6921","html_url":"https://github.com/benjamingr/bluebird-api","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamingr%2Fbluebird-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamingr%2Fbluebird-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamingr%2Fbluebird-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benjamingr%2Fbluebird-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benjamingr","download_url":"https://codeload.github.com/benjamingr/bluebird-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234134505,"owners_count":18784840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluebird","bluebird-api","native-promises","node-js","nodejs","promise","promises"],"created_at":"2024-10-10T07:37:10.053Z","updated_at":"2025-09-24T22:31:12.184Z","avatar_url":"https://github.com/benjamingr.png","language":"JavaScript","readme":"# bluebird-api\n\n## Introduction\n[Bluebird](https://github.com/petkaantonov/bluebird) compatible API on top of native promises as a drop-in replacement.\n\nWIP - contributions welcome.\n\n## Getting started\n\n* bluebird-api depends on node 7.0 and above\n\n```\n$ npm install bluebird-api\n```\nThen :\n```js\nconst Promise = require('bluebird-api');\n```\n## Contributing\n1. [Fork](https://github.com/benjamingr/bluebird-api#fork-destination-box) the repository\n2. ``git clone https://github.com/**your GH user**/bluebird-api``\n3. ``cd bluebird-api``\n4. ``npm install``\n5. ``npm test``\n\nBefore committing changes run `npm run build`\n\n\u003e  ***Commit build along with your changes to the repo.***\n\n## Why\nThere are [many reasons to use bluebird](http://bluebirdjs.com/docs/why-bluebird.html).\nAs native Promise implementations improve, bluebird-api allows keeping the same code but enjoying the benefits of improved native Promises.\n\n## API\n\nhttp://bluebirdjs.com/docs/api-reference.html\n\n### Core\n\n#### [Promise.then](http://bluebirdjs.com/docs/api/then.html)\n```js\n.then(\n    [function(any value) fulfilledHandler],\n    [function(any error) rejectedHandler]\n) -\u003e Promise\n\n```\n\n#### [Promise.catch](http://bluebirdjs.com/docs/api/catch.html)\n\n`.catch` is a convenience method for handling errors in promise chains. It comes in two variants - A catch-all variant similar to the synchronous `catch(e) {` block. This variant is compatible with native promises. - A filtered variant (like other non-JS languages typically have) that lets you only handle specific errors. ***This variant is usually preferable and is significantly safer.***\n\n\n#### [Promise.error](http://bluebirdjs.com/docs/api/error.html)\n\n```js\n.error([function(any error) rejectedHandler]) -\u003e Promise\n```\n\nLike `.catch` but instead of catching all types of exceptions, it only catches operational errors.\n\nNote, \"errors\" mean errors, as in objects that are `instanceof Error` - not strings, numbers and so on.\n\n#### [Promise.spread](http://bluebirdjs.com/docs/api/spread.html)\nLike calling .then, but the fulfillment value must be an array, which is flattened to the formal parameters of the fulfillment handler.\n```js\n.spread([function(any values...) fulfilledHandler]) -\u003e Promise\n```\n\n\n#### [Promise.finally](http://bluebirdjs.com/docs/api/finally.html)\n\n```js\n.finally(function() handler) -\u003e Promise\n\n.lastly(function() handler) -\u003e Promise\n```\n\nPass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for .finally in that the final value cannot be modified from the handler.\n\n\u003e Note: using `.finally` for resource management has better alternatives, see [resource management](http://bluebirdjs.com/docs/api/resource-management.html)\n\n#### [Promise.join](http://bluebirdjs.com/docs/api/promise.join.html)\nFor coordinating multiple concurrent discrete promises. While ``.all`` is good for handling a dynamically sized list of uniform promises, ``Promise.join`` is much easier (and more performant) to use when you have a fixed amount of discrete promises that you want to coordinate concurrently. The final parameter, handler function, will be invoked with the result values of all of the fufilled promises.\n```js\nPromise.join(Promise\u003cany\u003e|any values..., function handler) -\u003e Promise\n```\n#### [Promise.try](http://bluebirdjs.com/docs/api/promise.try.html)\nStart the chain of promises with ``Promise.try``. Any synchronous exceptions will be turned into rejections on the returned promise.\n```js\nPromise.try(function() fn) -\u003e Promise\n```\n#### [Promise.method](http://bluebirdjs.com/docs/api/promise.method.html)\nReturns a new function that wraps the given function ``fn``. The new function will always return a promise that is fulfilled with the original functions return values or rejected with thrown exceptions from the original function.\n```js\nPromise.method(function(...arguments) fn) -\u003e function\n```\n\n\n#### [Promise.suppressUnhandledRejections](http://bluebirdjs.com/docs/api/suppressunhandledrejections.html)\n\n```js\n.suppressUnhandledRejections() -\u003e undefined\n\n```\n\nBasically sugar for doing:\n```js\nsomePromise.catch(function(){});\n```\n\nWhich is needed in case error handlers are attached asynchronously to the promise later, which would otherwise result in premature unhandled rejection reporting.\n\n\n#### [Promise.onPossiblyUnhandledRejection](http://bluebirdjs.com/docs/api/promise.onpossiblyunhandledrejection.html)\n\n```js\nPromise.onPossiblyUnhandledRejection(function(any error, Promise promise) handler) -\u003e undefined\n```\n\n\u003e Note: this hook is specific to the bluebird instance its called on, application developers should use [global rejection events](http://bluebirdjs.com/docs/api/error-management-configuration.html#global-rejection-events)\n\nAdd `handler` as the handler to call when there is a possibly unhandled rejection. The default handler logs the error stack to stderr or `console.error` in browsers.\n\n```js\nPromise.onPossiblyUnhandledRejection(function(e, promise) {\n    throw e;\n});\n```\n\nPassing no value or a non-function will have the effect of removing any kind of handling for possibly unhandled rejections.\n\n\n\n### Timers\n#### [.delay](http://bluebirdjs.com/docs/api/delay.html)\nReturns a promise that will be resolved with ms milliseconds.\n```js\n.delay(int ms) -\u003e Promise\n```\n#### [.timeout](http://bluebirdjs.com/docs/api/timeout.html)\nReturns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within ms milliseconds, the returned promise is rejected with a TimeoutError or the error as the reason.\n```js\n.timeout(int ms, [String message=\"operation timed out\"]) -\u003e Promise\n---\n.timeout(int ms, [Error error]) -\u003e Promise\n```\n\n### Promisification\n#### [Promise.promisify](http://bluebirdjs.com/docs/api/promise.promisify.html)\nReturns a function that will wrap the given ``nodeFunction``. Instead of taking a callback, the returned function will return a promise whose fate is decided by the callback behavior of the given node function. The node function should conform to node.js convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument.\n```js\nPromise.promisify(\n  function(any arguments..., function callback) nodeFunction,\n  [Object { multiArgs: boolean=false, context: any=this } options]\n) -\u003e function\n```\n\n#### [Promise.asCallback](http://bluebirdjs.com/docs/api/ascallback.html)\n```js\n.asCallback(\n    [function(any error, any value) callback],\n    [Object {spread: boolean=false} options]\n) -\u003e this\n```\n```js\n.nodeify(\n    [function(any error, any value) callback],\n    [Object {spread: boolean=false} options]\n) -\u003e this\n```\n\nRegister a node-style callback on this promise. When this promise is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be `null` in case of success.\n\nReturns back this promise instead of creating a new one. If the `callback` argument is not a function, this method does not do anything.\n\n\n\n### Collections\n#### [.props](http://bluebirdjs.com/docs/api/props.html)\nLike ``.all`` but for object properties or ``Map``s entries instead of iterated values. Returns a promise that is fulfilled when all the properties of the object or the ``Map``'s values are fulfilled. The promise's fulfillment value is an object or a ``Map`` with fulfillment values at respective keys to the original object or a ``Map``. If any promise in the object or ``Map`` rejects, the returned promise is rejected with the rejection reason.\n```js\n.props(Object|Map|Promise\u003cObject|Map\u003e input) -\u003e Promise\n```\n#### [.each](http://bluebirdjs.com/docs/api/each.html)\nIterate over an array, or a promise of an array, which contains promises (or a mix of promises and values) with the given ``iterator`` function with the signature ``(value, index, length)`` where value is the resolved ``value`` of a respective promise in the input array. Iteration happens serially. If any promise in the input array is rejected the returned promise is rejected as well.\n```js\n.each(function(any item, int index, int length) iterator) -\u003e Promise\n```\n#### [.mapSeries](http://bluebirdjs.com/docs/api/mapseries.html)\nGiven an ``Iterable``(arrays are ``Iterable``), or a promise of an ``Iterable``, which produces promises (or a mix of promises and values), iterate over all the values in the ``Iterable`` into an array and iterate over the array serially, in-order.\n```js\n.mapSeries(function(any item, int index, int length) mapper) -\u003e Promise\n```\n#### [.map](http://bluebirdjs.com/docs/api/map.html)\nGiven an ``Iterable``(arrays are ``Iterable``), or a promise of an ``Iterable``, which produces promises (or a mix of promises and values), iterate over all the values in the ``Iterable`` into an array and map the array to another using the given mapper function.\n```js\n.map(function(any item, int index, int length) mapper, [Object {concurrency: int=Infinity} options]) -\u003e Promise\n```\n#### [.filter](http://bluebirdjs.com/docs/api/filter.html)\nGiven an ``Iterable``(arrays are ``Iterable``), or a promise of an ``Iterable``, which produces promises (or a mix of promises and values), iterate over all the values in the ``Iterable`` into an array and filter the array to another using the given filterer function.\n\n```js\n.filter(function(any item, int index, int length) filterer, [Object {concurrency: int=Infinity} options]) -\u003e Promise\n```\n\n### [.reduce](http://bluebirdjs.com/docs/api/promise.reduce.html)\n\n```js\nPromise.reduce(\n    Iterable\u003cany\u003e|Promise\u003cIterable\u003cany\u003e\u003e input,\n    function(any accumulator, any item, int index, int length) reducer,\n    [any initialValue]\n) -\u003e Promise\n```\n\nGiven an `Iterable`(arrays are `Iterable`), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the Iterable into an array and [reduce the array to a value](https://en.wikipedia.org/wiki/Fold_(higher-order_function) using the given `reducer` function.\n\nIf the reducer function returns a promise, then the result of the promise is ***awaited, before continuing with next iteration***. If any promise in the array is rejected or a promise returned by the reducer function is rejected, the result is rejected as well.\n\n\n### [.some](http://bluebirdjs.com/docs/api/promise.some.html)\n```js\nPromise.some(\n    Iterable\u003cany\u003e|Promise\u003cIterable\u003cany\u003e\u003e input,\n    int count\n) -\u003e Promise\n```\nGiven an `Iterable`(arrays are `Iterable`), or a promise of an `Iterable`, which produces promises (or a mix of promises and values), iterate over all the values in the `Iterable` into an array and return a promise that is fulfilled as soon as `count` promises are fulfilled in the array. The fulfillment value is an array with count values in the order they were fulfilled.\n\n\n#### [.any](http://bluebirdjs.com/docs/api/promise.any.html)\n\n```js\nPromise.any(Iterable\u003cany\u003e|Promise\u003cIterable\u003cany\u003e\u003e input) -\u003e Promise\n```\n\nLike `Promise.some`, with 1 as count. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.\n\n\n\n### Utility\n#### [.tap](http://bluebirdjs.com/docs/api/tap.html)\nAccept a resolved value (is not called for rejections) and passes value through to the next handler.\n```js\n.tap(function(any value) handler) -\u003e Promise\n```\n#### [.get](http://bluebirdjs.com/docs/api/get.html)\nConvenience method for getting a property of a resolved object.\n```js\n.get(String propertyName|int index) -\u003e Promise\n```\n#### [.call](http://bluebirdjs.com/docs/api/call.html)\nConvenience method for calling a method of a resolved object.\n```js\n.call(String methodName, [any args...])\n```\n#### [.reflect](http://bluebirdjs.com/docs/api/reflect.html)\nThe ``.reflect`` method returns a promise that is always successful when this promise is settled. Its fulfillment value is an object that implements the ``PromiseInspection`` interface and reflects the resolution of this promise.\n```js\n.reflect() -\u003e Promise\u003cPromiseInspection\u003e\n```\n\n\n#### [.noConflict](http://bluebirdjs.com/docs/api/promise.noconflict.html)\n```js\nPromise.noConflict() -\u003e Object\n```\nThis is relevant to browser environments with no module loader.\n\nRelease control of the `Promise` namespace to whatever it was before this library was loaded. Returns a reference to the library namespace so you can attach it to something else.\n\n\nThe `.reflect` method returns a promise that is always successful when this promise is settled. Its fulfillment value is an object that implements the [PromiseInspection](http://bluebirdjs.com/docs/api/promiseinspection.html) interface and reflects the resolution of this promise.\n\n\n#### [.return](http://bluebirdjs.com/docs/api/return.html)\n\n```js\n.return(any value) -\u003e Promise\n.thenReturn(any value) -\u003e Promise\n\n```\n\n#### Convenience method for:\n```js\n.then(function() {\n   return value;\n});\n```\nin the case where value ***doesn't change its value*** because its binding time is different than when using a closure.\n\n\n#### [.throw](http://bluebirdjs.com/docs/api/throw.html)\n```js\n.throw(any reason) -\u003e Promise\n.thenThrow(any reason) -\u003e Promise\n```\n\n#### Convenience method for:\n\n```js\n.then(function() {\n   throw reason;\n});\n```\n\nSame limitations regarding to the binding time of `reason` to apply as with `.return`.\n\nFor compatibility with earlier ECMAScript version, an alias `.thenThrow` is provided for `.throw`.\n\n\n#### [.catchReturn](http://bluebirdjs.com/docs/api/catchreturn.html)\n\n```js\n.catchReturn(\n    [class ErrorClass|function(any error) predicate],\n    any value\n) -\u003e Promise\n```\n\n#### Convenience method for:\n\n```js\n.catch(function() {\n   return value;\n});\n```\n\nYou may optionally prepend one predicate function or ErrorClass to pattern match the error (the generic `.catch` methods accepts multiple)\n\nSame limitations regarding to the binding time of `value` to apply as with `.return`.\n\n#### [.catchThrow](http://bluebirdjs.com/docs/api/catchthrow.html)\n\n```js\n.catchThrow(\n    [class ErrorClass|function(any error) predicate],\n    any reason\n) -\u003e Promise\n```\n\n#### Convenience method for:\n\n```js\n.catch(function() {\n   throw reason;\n});\n```\n\nYou may optionally prepend one predicate function or ErrorClass to pattern match the error (the generic `.catch` methods accepts multiple)\n\nSame limitations regarding to the binding time of `reason` to apply as with `.return`.\n\n### [.tapCatch](http://bluebirdjs.com/docs/api/tapcatch.html)\n\n`tapCatch` is a convenience method for reacting to errors without handling them with promises - similar to `finally` but only called on rejections. Useful for logging errors.\n\n### Generators\n\n#### [.coroutine](http://bluebirdjs.com/docs/api/promise.coroutine.html)\n\n```js\n\nPromise.coroutine(GeneratorFunction(...arguments) generatorFunction, Object options) -\u003e function\n```\n\nReturns a function that can use `yield` to yield promises. Control is returned back to the generator when the yielded promise settles. This can lead to less verbose code when doing lots of sequential async calls with minimal processing in between. Requires node.js 0.12+, io.js 1.0+ or Google Chrome 40+.\n\n\n### Deprecated\n\n#### .cast\nThis API is deprecated both in bluebird and bluebird-api, and exist in bluebird-api as part of backward compatibility.\n\n#### [.defer](http://bluebirdjs.com/docs/api/deferred-migration.html)\n\nDeferreds are deprecated in favor of the promise constructor. If you need deferreds for some reason, you can create them trivially using the constructor:\n\n```js\nfunction defer() {\n    var resolve, reject;\n    var promise = new Promise(function() {\n        resolve = arguments[0];\n        reject = arguments[1];\n    });\n    return {\n        resolve: resolve,\n        reject: reject,\n        promise: promise\n    };\n}\n```\n\n\n\n\n### Configuration\n\n#### [.done](http://bluebirdjs.com/docs/api/done.html)\n```js\n.done(\n    [function(any value) fulfilledHandler],\n    [function(any error) rejectedHandler]\n) -\u003e undefined\n```\n\nLike `.then`, but any unhandled rejection that ends up here will crash the process (in node) or be thrown as an error (in browsers). The use of this method is heavily discouraged and it only exists for historical reasons.\n\n\n\n\n\n### Resouce Management\n\n\n#### [.using](http://bluebirdjs.com/docs/api/promise.using.html)\n\n```js\nPromise.using(\n    Promise|Disposer|any resource,\n    Promise|Disposer|any resource...,\n    function(any resources...) handler\n) -\u003e Promise\n```\n\n```js\nPromise.using(\n    Array\u003cPromise|Disposer|Any\u003e resources,\n    function(Array\u003cany\u003e resources) handler\n) -\u003e Promise\n```\n\n\nIn conjunction with `.disposer`, `using` will make sure that no matter what, the specified disposer will be called when the promise returned by the callback passed to `using` has settled. The disposer is necessary because there is no standard interface in node for disposing resources.\n\n\n\n#### [.disposer](http://bluebirdjs.com/docs/api/disposer.html)\n```js\n.disposer(function(any resource, Promise usingOutcomePromise) disposer) -\u003e Disposer\n```\nA meta method used to specify the disposer method that cleans up a resource when using `Promise.using`.\n\nReturns a Disposer object which encapsulates both the resource as well as the method to clean it up. The user can pass this object to `Promise.using` to get access to the resource when it becomes available, as well as to ensure it's automatically cleaned up.\n\nThe second argument passed to a disposer is the result promise of the using block, which you can inspect synchronously.\n\n\n\n## License\nSome tests under MIT license for Kris Kowal, Petka Antonov and Brian Cavalier\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenjamingr%2Fbluebird-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenjamingr%2Fbluebird-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenjamingr%2Fbluebird-api/lists"}