feat — Support npm package (bare module specifier) as a mutator path

[wadakatu]

Background

Split out from #411. While #411's reproduction (a transformer rewriting mutator.path) is being fixed as a bug, the comments raised a distinct, broader request: being able to point a mutator at an npm package instead of a local file.

It is not possible to use mutator from npm library.
— @aizerin, follow-up

This is filed as its own issue so it is not lost when the #411 bug fix lands, and because it is a feature (not a bug).

Current behavior

mutator: {
  path: '@my-scope/axios',
  name: 'useAxiosInstance',
}

fails with:

ENOENT: no such file or directory, open '.../@my-scope/axios'

Reproduced on orval v8.10.0.

Root cause:

• normalizeMutator (packages/orval/src/utils/options.ts) always runs nodePath.resolve(workspace, path), turning a bare module specifier @my-scope/axios into <workspace>/@my-scope/axios.
• generateMutator (packages/core/src/generators/mutator.ts) then does fs.readFile(importPath) on that non-existent path.

There is currently no way to consume a mutator that is published/shared as an npm package. The only workaround is require.resolve() + post-processing, as noted in the issue comments.

Problem

Teams that share a single HTTP client / mutator across multiple repositories want to distribute it as an npm package. Today they must vendor a local copy or post-process the generated output.

What to do

Support a bare module specifier as mutator.path:

• In normalizeMutator: detect bare module specifiers (not relative .//../, not absolute) and keep path verbatim instead of resolving it against the workspace.
• In generateMutator: for a bare specifier, resolve the real file for introspection (e.g. via require.resolve from the workspace) so numberOfParams / ErrorType / BodyType detection still works; emit the import path verbatim instead of computing a relative path.
• getMutatorInfo's esbuild step already resolves bare entry points via node_modules (verified), so the introspection bundling itself needs no change.
• Document the npm-package mutator option in docs/.../output.mdx.

Note: introspecting TypeScript-only types (ErrorType/BodyType) from a published package shipping compiled .js is inherently limited; that limitation is acceptable and should be documented.

Goal

• mutator: { path: '@my-scope/axios', name: 'useAxiosInstance' } produces import { useAxiosInstance } from '@my-scope/axios' and generation succeeds.
• Works across all output modes (single, split, tags, tags-split).
• Covered by tests and documented.

[chippleh1392]

I took a closer look at this. normalizeMutator currently resolves every mutator path against the workspace, while the same normalized path is later used for source inspection and the generated import. That turns a package specifier into a nonexistent local path.

I would keep the original specifier for generated imports and use a separately resolved package entry for inspection, without changing existing local mutator behavior. I would cover package names and exported subpaths across the output modes.

@wadakatu, are you already planning to work on this? @melloware, if not, would a PR with that scope be welcome?

[wadakatu]

@chippleh1392

I haven’t started implementing this yet, so please feel free to open a PR — that would be really appreciated!