fix(core)!: keep literal request headers named after a method - #11156

Summary

Request preparation removes common and method-named defaults after flattening them. Since #11096 extended cleanup to every supported method, literal headers such as Link have also been removed. Treating every object as a defaults bucket additionally drops Date, Buffer, typed-array, and application class values before normal header serialization.

Limit defaults buckets to plain/null-prototype maps and compatible AxiosHeaders, including subclasses and instances from another package build. Other values reach normal header serialization. Common defaults apply to every request; method defaults apply only to the matching method.

Breaking compatibility change: custom class instances used as defaults buckets must be converted to a plain map or AxiosHeaders. Otherwise they become literal header values, including on nonmatching requests.

Linked issue

No separate issue. Fixes the literal-header regression introduced by #11096 and addresses the non-plain object finding, throwing brand-probe finding, and tag-only misclassification finding.

Changes

• Recognize plain header maps and local AxiosHeaders; require the AxiosHeaders symbol brand and the core header-container interface for foreign instances (toJSON, set, get, has, delete, clear, normalize, concat, toString, and iteration). A tag and toJSON alone do not classify an application object as a defaults bucket. Methods are checked for callability without invoking them, and getSafeProp excludes shared-prototype values.
• Catch errors from the optional foreign-instance probes. Throwing brand or interface getters now fall back to literal-header serialization; genuine serialization errors still reject the request.
• Cover scalar and non-plain values, matching/nonmatching methods, common defaults, precedence, subclasses, cross-build instances, shared-prototype pollution, own/inherited throwing getters, and tagged application literals. Packed ESM/CJS tests also cover foreign subclasses. Preserve nullish cleanup and false-valued omission.
• Update the existing prerelease changelog entry and record the class-defaults migration in deferred release documentation.

Validation

Environment: macOS arm64, Node.js 24.18.0, npm 11.16.0. Base: v1.x at f694ecd6. Latest fix: d2a6e81f.

• npm ci --ignore-scripts: passed in the root and both smoke fixtures.
• Before the interface-validation fix, npm run test:vitest:unit -- tests/unit/axios.test.js reproduced both new tagged-literal failures while the existing 37 tests passed. The final focused run, including own/inherited interface-getter failures, the serialization-error negative case, and tests/unit/syntaxCompat.test.js, passed 113 tests (41 Axios + 72 syntax checks). The earlier throwing-brand regression coverage remains intact.
• npm run lint and npm run build: passed.
• npm run test:vitest:unit: 1,604 passed across 69 files.
• npm run test:vitest:browser:headless: 858 passed, 3 skipped across Chromium, Firefox, and WebKit. Installed Playwright browsers were available.
• npm pack --silent --pack-destination <temporary-directory>, then npm install --no-save --ignore-scripts --package-lock=false <tarball> in each smoke fixture: passed.
• npm run test:smoke:esm:vitest in tests/smoke/esm: 78 passed, including ESM/CJS constructor and subclass interoperability.
• npm run test:smoke:cjs:mocha in tests/smoke/cjs: 72 passed, including defaults and subclasses from another packaged build.
• Prettier checks for the changed files and changed browser test block and git diff --check: passed. Final diff inspected; no dependency, workflow, generated-artifact, version, debug, or focused-test changes.

GitHub Actions for d2a6e81f5d0a7c3b49ee08087214ff5a6977706e require approval (action_required): Continuous integration, Bundle Size, zizmor, and build reproducibility. Their runtime/build results remain unverified on GitHub. The PR is conflict-free. Review bot results are separate from build/test evidence.

Compatibility and documentation

Semver: major compatibility impact for arbitrary class defaults. Plain/null-prototype maps and compatible AxiosHeaders retain defaults-bucket behavior. Other objects are literal header values. Applications using custom class instances as defaults maps must materialize their own enumerable header entries:

// Before
headers: { post: customDefaults }

// Migrate to either form
headers: { post: { ...customDefaults } }
headers: { post: new AxiosHeaders({ ...customDefaults }) }

Without migration, a custom toString() may expose object contents in a literal header, including on nonmatching requests. This intentional restriction must be accounted for when scheduling the release; the overall PR is not a universally nonbreaking patch. Foreign header containers retain support through structural interface validation; tag-only application objects remain literal values. Failed optional probes fall back to normal serialization.

No new APIs, options, exports, dependencies, or declaration changes. Object-to-string normalization is existing JavaScript behavior and does not expand TypeScript header-value declarations. PRE_RELEASE_CHANGELOG.md describes the final behavior; PRE_RELEASE_DOCS.md records deferred header/defaults guidance and migration. README and docs-site updates remain deferred to release preparation.

Type/module declaration tests are not applicable because declarations and exports are unchanged; both runtime package formats were tested from the tarball. The full GitHub runtime matrix, including Bun and Deno, was not reproduced locally.

Checklist

• Scope, target branch, and linked issue/rationale checked
• PRE_RELEASE_CHANGELOG.md entry added or updated
• Regression tests and relevant negative/platform cases covered
• Applicable local checks completed successfully; commands, results, and runtime versions recorded above
• Deferred release docs and ESM/CJS types/tests updated where needed, or applicability explained
• Semver impact stated and intentional breaking changes explained
• Final diff reviewed for security, unrelated changes, generated artifacts, and test/debug leftovers
• Latest GitHub Actions status recorded separately from review/security bot results