All jobs

Migrate From Bluebird to Native Promises in a Node.js Library

Yes. An agent replaces Bluebird helpers with native promises, and finds the places where Bluebird is part of your public API and cannot simply go.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Bluebird usually enters a file as const Promise = require('bluebird'), which hides the built-in Promise for everything below it. The agent's first job is to sort the uses under that line into three groups: calls every promise has, helpers only Bluebird has, and promises handed to someone else's code. In a library like sheerun/knex-migrate, package.json lists bluebird ^3.4.6 and src/index.js has that shadowing line. Below it are three Promise.promisify(fs.stat, { context: fs }) style calls for stat, readFile and writeFile, one .return(...) chained on the last of them, and two plain Promise.resolve calls.

The third group is the one that decides the outcome. The migration runner is configured with params: [connection, Promise], so every migration file a user writes is called as up(knex, Promise) and receives Bluebird as its second argument. Nothing in the repository uses that argument. The generated stub is exports.up = async function(knex), and the three example migrations take knex alone. But users' migrations are not in the repository, and any of them may call Promise.map or Promise.mapSeries on what they were given.

The repository cannot answer that with tests, because src/index.test.js is a single test.todo. So the agent builds its own check from the example directory. It installs sqlite3, runs the CLI's up, list, generate and down --to 0 against knexfile-custom.js, and saves the output. It adds a temporary migration whose up calls Promise.mapSeries on its second argument, and runs it before any edit: it applies. Then it removes Bluebird everywhere and runs again. The three stock migrations apply and the fourth stops the run with Promise.mapSeries is not a function and exit status 1.

With that on record the agent splits the change. Internal uses go native: util.promisify(fs.stat) and its siblings, which keep the engines floor of Node 8 where fs.promises would raise it, and .then(() => value) in place of .return(value). The object passed to migrations stays Bluebird, under an explicit name, and the description proposes dropping it in the next major version. It also checks what users install either way: yarn why bluebird shows umzug, a runtime dependency, requiring Bluebird itself.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Reduce this Node.js project's use of bluebird to what its public behaviour requires, and use native promises everywhere else. Find every file that requires bluebird, noting where it is assigned to a variable named Promise. Classify each use below that line: standard calls (resolve, reject, all, race, then, catch, finally), Bluebird-only helpers (promisify, promisifyAll, map, mapSeries, each, props, delay, tap, spread, return, catch with an error class, cancellation), and any place a Bluebird promise or the Bluebird constructor is returned to or passed into code outside this package (callbacks, plugins, user files, exported functions). Run the tests; if there are none worth the name, build a check from the repository's example or CLI and record its output first. Port the internal uses: util.promisify or fs.promises according to the engines field, async functions or small loops for map and mapSeries, then() for return and tap. For anything in the third group, write a temporary user-side file that depends on a Bluebird-only helper, run it before and after, and if it breaks, keep the old behaviour there and report it as a change for the next major version. Run yarn why bluebird or npm ls bluebird at the end. Open a pull request with the classification, the commands and their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that edits src/index.js only. Bluebird stays in package.json, now imported under a name that says what it is for, and the description explains why with the failing probe: the command, the migration file and the Promise.mapSeries is not a function line. Above that is the classification of every use, and the CLI output for up, list, generate and down before and after, which is the same.

The reviewer gets a smaller change than the title of the task suggests, on purpose. Removing the dependency outright is a breaking release for anyone whose migrations lean on the second argument, and the pull request gives the maintainers what they need to plan that: which line to change, what error users would see, and the fact that the package would still arrive through umzug. One more difference is noted for completeness. Bluebird's promisify rejects with its own OperationalError wrapper where the native one rejects with the plain Error; nothing in this file catches by class, so no caller is affected.

Run it on every Monday morning

Give the Project an automation with a schedule trigger, cron set to 0 7 * * 1 and a timezone, and the prompt above. A run starts each week in the repository. Once the internal uses are gone it reports only the public ones that remain, so the weekly result shrinks to a reminder of the open major-version item.

For an organisation with many small packages, a script that posts this body once per repository to POST /o/{org}/sessions finishes the survey in one pass. Use a request_id that is a UUID v5 of each repository's name so a rerun of the script does not start duplicates.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

The dangerous part of this migration is invisible in the package's own code: a promise implementation that leaks to users through an argument. Finding it takes reading the configuration of a third-party runner, and proving it takes a database, a throwaway migration and two runs of the CLI. The agent does both in its sandbox, where installing a native SQLite driver and creating scratch database files costs nothing, and the commands and outputs are kept in the run.

A project with a single test.todo is also exactly where a person is tempted to trust the diff. The run replaces that trust with a recorded before and after of the tool's real commands, attached to the pull request.

Frequently asked questions

What replaces Promise.promisify?

util.promisify from Node's standard library, available since Node 8, or the ready-made fs.promises functions on Node 10 and later. The { context: fs } option has no counterpart and is not needed for fs functions. The agent picks between the two by reading the engines field.

What about Promise.map and Promise.mapSeries?

Promise.all(items.map(fn)) covers map without a concurrency limit, and a for loop with await covers mapSeries. A map call that sets concurrency needs a small limiter. This library has none of these internally; they matter here because users may call them on the object the library hands over.

Why keep Bluebird at all?

Because it is part of the contract. Each migration receives it as a second argument, and a migration that calls a Bluebird-only helper on it fails once that argument is the built-in Promise. The agent shows the failure and leaves the decision about a major release to the maintainers.

Will Bluebird disappear from node_modules afterwards?

Not in this project even after a full removal. umzug 2 depends on it, and so does the knex release in devDependencies. The agent runs yarn why bluebird and includes the answer so nobody expects a smaller install from this change alone.

More jobs like this: Upgrade dependencies weekly

Keep reading