All jobs

Migrate From the Deprecated @hapi/joi Package to joi

Yes. An agent replaces the deprecated @hapi/joi with joi, shows that validation messages your API returns are unchanged, and opens a pull request.

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

What the agent does

@hapi/joi stopped at 17.1.1 and npm prints its notice on every install: Switch to 'npm install joi'. The library moved to the unscoped name, and two of the old package's own dependencies, @hapi/address and @hapi/formula, carry deprecation notices as well. The agent starts by finding where schemas are built and where they are consumed, because those can be different files. In an Express API like cornflourblue/node-mongo-jwt-refresh-tokens-api, package.json has "@hapi/joi": "^17.1.1" and one file requires it: users/users.controller.js, which builds Joi.object({...}) schemas for the authenticate and revoke-token routes. _middleware/validate-request.js never imports the library. It receives a schema and calls schema.validate(req.body, options) with abortEarly: false, allowUnknown: true and stripUnknown: true.

The require line is the whole code change, so the work is in showing that nothing a client sees moves. In this API the validation text is a response body. validate-request.js joins error.details into a string beginning Validation error: and passes it to next, and _middleware/error-handler.js answers a string error with status 400 and { message: err }. A reworded message in the new package would be an API change. The agent installs the old and new packages side by side, builds both route schemas with each, and feeds them the same bodies: an empty object, a missing password, a number where a string belongs, an empty string, an unknown extra key, an empty token, and no body. It prints each message and each returned value and diffs the two columns.

It then picks the version on evidence. The current joi major requires Node 20 or newer in its engines field, and npm also keeps a latest-17 tag for the 17 line. This repository has no engines field and no .nvmrc, so the agent reports the Node version it tested on, takes the newest major that version satisfies, and runs the same comparison against the 17 line so the pull request shows both would be safe. It regenerates package-lock.json, which is still lockfileVersion 1, with the npm it has, and says that the lock format changed as a side effect.

One rule shapes the diff. Schemas from two copies of the library cannot be combined: nesting an @hapi/joi schema inside a joi object, in either direction, throws Cannot mix different versions of joi schemas. So the agent converts every file that builds a schema in the same commit and searches node_modules for other packages that depend on either name, such as a validation middleware that bundles its own copy. Here there are none. The app's routes need MongoDB, which _helpers/db.js connects to at load, so the agent exercises the schemas and the middleware directly with a stub request and reports that no route was called over HTTP.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Replace the deprecated @hapi/joi package with joi in this Node.js project. Read package.json, the lock file and every file that requires or imports @hapi/joi, and also find the files that receive schemas and call validate, validateAsync, assert or attempt on them, with the options they pass. Trace what happens to a validation error: which text reaches the HTTP response. Before editing, install joi under an alias next to the existing package and write a script that builds each of this project's schemas with both libraries and validates the same inputs with the project's own options: a valid body, each required field missing, a wrong type, an empty string, an unknown extra key and no body at all. Print the error messages and the returned values for both and state whether any differ. Choose the newest joi major whose engines field the project's Node version satisfies; read that version from engines, .nvmrc, a Dockerfile or CI, and if none says, report the Node version you ran and repeat the comparison on the previous major too. Then change every require in one commit, because schemas from two joi packages cannot be mixed, and check node_modules for other packages that depend on either name. Remove @hapi/joi, update the lock file, and show npm install printing no deprecation notice for it. Do not change the options, the schemas or the error format. Start the app only if its database is reachable in the sandbox; otherwise test the validation middleware with a stub request and say so. Open a pull request with the script and its 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 changes one line in users/users.controller.js, the dependency in package.json and the lock file. The description carries the comparison table, one row per input and schema, with the message from @hapi/joi and the message from joi beside each other. For the two schemas in this repository the expected finding is that every row matches, including the stripped extra key and the empty token that Joi.string().empty('') turns into an absent field; a row that differs is called out at the top, not buried.

The reviewer checks the version line and its reason, since the major chosen sets the minimum Node the service can run on. They check that the diff to package-lock.json is explained: old transitive packages such as @hapi/address 4 and @hapi/formula 2 leave, and the new package's dependencies arrive. And they read what was not tested. The description says the routes were not called against MongoDB, that server.js still uses body-parser, which is a separate cleanup, and that nothing in the schemas or the middleware options was edited.

Run it on every npm deprecation warning in CI

Deprecation notices scroll past in install logs and nobody files them. A step in your CI can catch one: run npm ci, search its output for deprecated warnings (npm 10 prints them as npm warn deprecated), and when a line appears, send it to an automation's webhook trigger. Create the automation on the Project with the prompt above, rewritten to name the package generally ("the deprecated package named in the text after this prompt"), and call the trigger with Authorization: Bearer <secret>. The posted text, up to 64 KB, is placed after the prompt.

Call the trigger's URL with an Idempotency-Key header made of the repository and package name, so the same warning on the next fifty builds starts nothing new. The automation's max runs per hour is a second limit if several packages are flagged in one install.

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

Why run it on Rush?

A rename is the kind of change people merge on trust, and trust is all a laptop check usually produces. The run builds the project's real schemas under both packages in its own sandbox and records every message each one returns. When the text of a 400 response is part of the contract, as it is here, that table is the review.

The run is also disposable in a way that suits this job. It installs two or three copies of the library under aliases, pokes at how they refuse to mix, regenerates a lock file, and none of that touches a developer's node_modules. Each command and its output stays in the session transcript, so a reviewer can see the exact install that printed no deprecation notice.

Frequently asked questions

Is joi the same library as @hapi/joi?

Yes. The project left the hapi organisation's npm scope and continued under the name joi, starting from the same 17.x code. The schema API (Joi.object, Joi.string().required(), validate) is the same, which is why the migration is normally one line per file.

Why do I get "Cannot mix different versions of joi schemas"?

Some module still builds schemas with the old package and passes them into an object built with the new one, or a dependency ships its own copy. Each copy only accepts its own schema objects. Convert every file in one change and run npm ls joi @hapi/joi to find the stray copy.

Should I move to joi 17 or the latest major?

It depends on your Node version. The latest major declares Node 20 or newer, and the 17 line remains published under the latest-17 tag for older runtimes. The agent reads your Node version from the repository, picks accordingly and shows the comparison for both.

Will my validation error messages change?

The agent does not assume either way; it measures. It validates the same inputs with both packages using your options and diffs the messages. If a message differs for one of your schemas, the pull request shows the old and new text so you can decide whether clients depend on it.

Does this work with TypeScript?

Yes. joi ships its own type definitions, so a @types/hapi__joi dev dependency is removed in the same change if you have one. The agent runs your type check after the swap and includes its output.

More jobs like this: Upgrade dependencies weekly

Keep reading