All jobs

Migrate From querystring to URLSearchParams in a Node.js API Client

Yes. An agent replaces querystring with URLSearchParams, keeps empty, missing and repeated values encoded as before, 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

URLSearchParams is the standard way to build and read query strings, in Node and in browsers, and the npm package named querystring now installs with a notice that calls its API legacy. The two do not produce the same string for the same object, and the differences land exactly where API clients are sloppy. feross/last-fm is a good example. index.js requires Node's querystring once and uses it on one line, inside _sendRequest: it adds api_key and format to the caller's parameters and appends querystring.stringify(params) to the Last.fm endpoint. That single line serves 26 calls to _sendRequest. Fifteen of them pass limit: opts.limit and eleven pass page: opts.page, whether or not the caller set those options.

That habit is the trap. When limit was never set, querystring.stringify writes limit=, an empty value. new URLSearchParams(params) writes limit=undefined, a literal word the API has to make sense of. The agent finds this by reading the call sites before editing, then confirms it by printing both encodings for a representative set of parameters taken from the code. It fixes the cause in the one shared place: _sendRequest drops keys whose value is missing before building the string, so no method sends a parameter the caller did not supply.

It checks the other differences against what this client actually sends. A space becomes + where it was %20; both are valid in a query string and servers decode them alike, but a test or a request signature that compares raw URLs would notice. URLSearchParams percent-encodes (, ), ', ! and ~, which querystring leaves as they are, and artist names contain such characters. An array value is joined with commas into one parameter where querystring repeated the key. No method in this client passes an array, so the agent records that and moves on.

The project's npm test is standard && node -e "require('./')": a lint pass and a check that the file loads. Nothing in it would catch a changed URL. The agent adds a small test that replaces the HTTP call with a recorder and asserts the exact URL for a search with and without limit, so the behaviour it just reasoned about is pinned down. It makes no live request to Last.fm, which would need an API key.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Migrate this project from the querystring module to URLSearchParams. Find every use: require or import of querystring (Node's built-in or the npm package), and calls to stringify, parse, escape and unescape. For each call, read the callers and list what kinds of values reach it: missing values, null, empty strings, numbers, booleans, arrays, nested objects, and strings with spaces or punctuation. Before changing code, print the output of the old and new encoders for realistic inputs taken from the call sites and show the differences. Then replace each call so that the request the server receives means the same thing: leave out keys whose value is missing instead of sending a placeholder word, repeat keys for arrays with append if the old code repeated them, and where parse results were read as arrays use getAll. If any code compares or signs the raw query string, keep its byte-for-byte format and say how. Remove the querystring package from the manifest and lockfile if it was a dependency. Add tests that assert the exact URL or parsed result for the cases you found, without calling external services; stub the HTTP layer. Run the project's lint and test commands and report their output. State the minimum Node version the new code needs. Open a pull request.",
  "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, for last-fm, changes a few lines of index.js and adds one test file. The require line goes, _sendRequest filters its parameters and builds the string with URLSearchParams, and nothing else in the 26 methods changes. The description contains the comparison table the agent prints: the same parameters through both encoders, with the three differences that apply to this client marked, and the ones that do not apply listed as checked.

It names one behaviour change it chose on purpose. Parameters the caller did not set are no longer sent as empty values, they are absent. Whether the API treats an absent parameter like an empty one is answered from the API's documentation, not from a live call, and the description quotes what it relied on. The new test asserts both URLs so a later edit cannot bring the placeholder word back.

A reviewer with an API key runs one real search with the branch and compares the response to the released version. That is the step the agent cannot do without credentials, and the description says so.

Run it on every Linear issue labelled tech-debt

Clean-ups like this live in a backlog, so let the backlog start them. Connect Linear under Settings → Connections, save the prompt above as an automation on the repository's Project, and add a linear trigger on linear.issue.labeled with the label your team uses for this kind of work. When someone in your Rush org adds the label, a run starts with the issue placed after the saved prompt as event text. The trigger fills in no placeholder, so the prompt has to stand on its own. Changes made by an app integration never fire it.

Write the issue so the event text helps: name the module to replace and any endpoint whose URL format must not change. An automation's runs are capped by its max runs per hour. Label many issues at once and the events past the cap wait as queued runs until the hour has room, and at most one more hour's worth can wait.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Nobody budgets time to compare two encoders, so this migration is usually done by search and replace and discovered wrong in production, when a third-party API starts rejecting a parameter that reads as a word. The comparison is cheap for an agent: it runs both functions on inputs lifted from the code, in its own sandbox, and the printed table stays in the session. The reviewer sees the evidence for each difference instead of a statement that the output is equivalent.

Running in the cloud also means the work does not wait for someone's afternoon. The label goes on, the run reads all 26 call sites, writes the test the project never had, and comes back as a pull request with the lint and test output attached. If the checks do not pass, the run ends needs_review and says why.

Frequently asked questions

Is Node's querystring module deprecated?

The built-in module still ships with Node and loads without a warning. The separate npm package called querystring is marked deprecated, and its notice tells you to use URLSearchParams for new code. If your package.json lists that package, you can remove it.

Why does my URL now contain `limit=undefined`?

URLSearchParams converts every value to a string, so a missing value becomes the text undefined and null becomes null. querystring.stringify wrote an empty value for both. Remove keys with missing values before constructing the parameters.

Does URLSearchParams encode spaces differently?

Yes. It writes + for a space and querystring wrote %20. Servers decode both the same way in a query string. It matters only where your code compares, caches or signs the raw string, and those places need the old format kept or the comparison updated.

How do I get repeated keys as an array?

querystring.parse('a=1&a=2') gave you an array under a. With URLSearchParams, get('a') returns the first value and getAll('a') returns all of them. Converting with Object.fromEntries keeps only the last, which is a common way to lose data in this migration.

Will this work in older Node versions?

URLSearchParams has been a global since Node 10, so any supported release has it without an import. The agent states the minimum version the new code needs and checks it against the engines field or CI configuration, which in last-fm is lts/* in .travis.yml.

More jobs like this: Turn a Linear label into a PR

Keep reading