All jobs

Fix Deprecated Zod 4 APIs in a TypeScript API

Yes. An agent finds each deprecated Zod call from the installed typings, replaces it without changing output, reruns typecheck and tests and opens a PR.

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

What the agent does

The agent starts from the versions on disk, since a deprecation is a note in one release's typings and not a general fact. In a TypeScript API like w3cj/hono-open-api-starter, package.json asks for zod ^4.0.14 and pnpm-lock.yaml resolves 4.0.14, beside @hono/zod-openapi 1.0.2, drizzle-zod 0.8.2 and stoker 2.0.1. The README says the starter was moved to Zod 4 after its video was recorded and links the commit. That move left Zod 3 idioms that still compile. Zod is used in a handful of places: src/env.ts validates the environment, src/db/schema.ts derives insert and select schemas from the Drizzle table, src/lib/zod-utils.ts holds a cast helper, and src/routes/tasks/tasks.test.ts asserts on issue codes and messages.

It takes a baseline, and the baseline is not clean. pnpm typecheck passes. pnpm test passes its one file after beforeAll runs pnpm drizzle-kit push against the file:test.db named in .env.test. pnpm lint fails before any change, on an unused z import at the top of src/db/schema.ts. And nothing in the project can see a deprecation: eslint.config.mjs calls @antfu/eslint-config with typescript: true and no tsconfigPath, so no type-aware rule runs, and there is no workflow under .github. The agent makes the compiler's knowledge visible for one pass by linting src with a throwaway config that sets tsconfigPath and turns on ts/no-deprecated. That reports five uses in three files, each with the note from Zod's own typings: .url() on a string, ZodIssueCode twice, flatten on an error, and ZodTypeAny.

Each replacement is small, and the agent checks that it changes nothing a caller can observe. z.string().url() becomes z.url(), and the agent confirms the development value file:dev.db still parses. z.ZodIssueCode.invalid_type becomes the string "invalid_type" in env.ts, and in the test ZodIssueCode.too_small becomes "too_small" and its import goes. ZodTypeAny in the cast helper becomes ZodType. The flatten call takes a decision: the deprecation note points to z.treeifyError, which returns a different shape, and this code prints fieldErrors for a person reading a failed boot. The agent uses z.flattenError(error).fieldErrors, which exists in 4.0.14 and keeps the shape, then starts the app with a bad LOG_LEVEL and a bad DATABASE_URL before and after and compares the printed block, which comes out identical.

Then it draws the line around the job. superRefine in env.ts carries no deprecation note in this version's typings, so it stays. The toZodV4SchemaTyped cast and the @ts-expect-error on patchTasksSchema exist because drizzle-zod, the z that @hono/zod-openapi exports and zod/v4 do not agree on types at these versions; removing them means upgrading those packages, which is a different pull request. src/lib/constants.ts hard-codes Zod's message text, such as Invalid input: expected number, received NaN, for the tests to compare against, which will break on a wording change upstream; the agent notes it. It reruns pnpm typecheck and pnpm test, runs the deprecation lint again to see zero reports, and removes the unused import only if the prompt allows, since it predates the task.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Remove deprecated Zod API usage from this TypeScript API. Read package.json, pnpm-lock.yaml (resolved zod, @hono/zod-openapi, drizzle-zod and stoker versions), eslint.config.mjs, tsconfig.json, vitest.config.ts, .env.example, .env.test, the README, src/env.ts, src/db/schema.ts, src/lib/zod-utils.ts, src/lib/constants.ts and everything under src/routes first. Run pnpm install --frozen-lockfile, pnpm typecheck, pnpm lint and pnpm test before changing anything and record the result of each; a failure that exists before your change is reported, not hidden. Find deprecated uses from the installed typings, not from memory: lint src once with a temporary type-aware ESLint config that enables ts/no-deprecated, list every report with file, line and the deprecation note, and do not commit that config. Replace each use with the API the note or Zod's documentation names, keeping behaviour identical: where a replacement would change output, such as the shape printed for an invalid environment, pick the one that keeps it and show the output before and after. Do not upgrade any package, do not remove the toZodV4SchemaTyped cast or the @ts-expect-error in src/db/schema.ts, and do not rewrite code that has no deprecation note. You may remove the unused import that makes pnpm lint fail, in its own commit. Rerun typecheck, tests and the deprecation lint, and open a pull request with a table of each deprecated use and its replacement, the command output before and after, and a list of what you saw and left alone with the reason.",
  "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 three files by a few lines each: src/env.ts, src/lib/zod-utils.ts and src/routes/tasks/tasks.test.ts, plus a one-line commit to src/db/schema.ts if the unused import was in scope. No dependency moves and the lockfile is untouched. The description opens with the table of deprecated uses, giving file and line, the text of the note the typings carry, and the replacement chosen. The flatten row has a sentence of its own, because the agent did not follow the note's suggestion and explains why the output had to stay the same.

Under the table are the commands. Typecheck and tests are shown before and after. The lint is shown with its pre-existing error, and the temporary deprecation lint is shown going from five reports to none, with the config it used pasted in the description and not committed. A last section lists what was seen and left: the cast helper and the @ts-expect-error, superRefine, the hard-coded message strings, and the fact that the repository has no CI workflow to run any of this on the next pull request.

A reviewer checks that the environment validation still fails closed: an invalid variable still prints the same block and exits with code 1. They check the test now compares against a string literal that is the real issue code, not a typo that happens to match nothing. And they decide whether to keep the deprecation rule on for good, knowing what it brings: with tsconfigPath set, the preset enables its other typed rules too, and in the agent's check ts/strict-boolean-expressions fired on src/env.ts.

Run it on every first of the month

Deprecations arrive with minor releases, and a caret range like ^4.0.14 takes them the next time the lockfile is refreshed. Create an automation in the Project that holds the repository with a schedule trigger whose cron is 0 9 1 * * in your timezone, and a prompt that says: lint src with ts/no-deprecated enabled; if it reports nothing, end with one line; otherwise replace each use as its note says, keep output identical, run typecheck and tests and open a pull request. It runs as the member who last changed the automation, and turning it off pauses it without losing the prompt.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The reliable list of deprecated calls is in node_modules, in the typings of the exact version the lockfile resolves, and reading it needs an install and a type-aware pass over the source. Sent from a terminal as one request, it happens in the agent's sandbox on a fresh clone, and the list in the pull request matches what your build resolves and not what a migration guide said about a different minor.

The second half of the job is proving that nothing changed, and that is commands too: typecheck, the test file that pushes a schema to a scratch SQLite database, and the application booted with bad variables to compare its output. All of it is kept in the session's transcript at GET /o/{org}/sessions/{id}/messages, each command with its output. The reviewer does not have to trust that z.flattenError prints the same block as the old method; both printouts are there.

Frequently asked questions

How does the agent know which Zod calls are deprecated?

From the @deprecated notes in the typings of the version your lockfile resolves, surfaced by a type-aware lint rule. For Zod 4.0.14 that includes .url() on a string, ZodIssueCode, ZodTypeAny and flatten on an error. A method with no note in your version is left alone, even if a newer release deprecates it.

Is error.flatten() replaced by z.treeifyError?

That is what the note suggests, but the two return different shapes. Where code reads fieldErrors, as this project's environment check does, z.flattenError(error) is the function that keeps the shape. The agent picks by what the surrounding code consumes and shows the output before and after.

Will this upgrade Zod or related packages?

No. The request forbids version changes, and the lockfile is not touched. Workarounds that exist because of how drizzle-zod and @hono/zod-openapi type their schemas stay until those packages are upgraded, and the pull request lists them so that job can be scheduled.

More Zod jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading