fix(types): constrain AxiosHeaders custom fields by LaplaceYoung · Pull Request #10941 · axios/axios

LaplaceYoung · May 24, 2026

Summary

Tighten the AxiosHeaders string index signature to accepted header values or declared methods in both ESM and CJS typings.
Add module typing coverage for valid custom header fields and a rejected Promise assignment.
Runtime behavior remains unchanged.

Tests

.\node_modules\.bin\mocha --timeout 10000 tests\typings.module.test.cjs (from tests/module/cjs)
npx vitest run --config vitest.config.js --project module tests/typings.module.test.js (from tests/module/esm)
npx prettier --check index.d.ts index.d.cts tests/module/esm/tests/typings.module.test.js tests/module/cjs/tests/typings.module.test.cjs tests/module/esm/tests/helpers/headers-types.ts tests/module/cjs/tests/helpers/headers-types.ts
git diff --check

Summary by cubic

Constrain AxiosHeaders string index to valid header values while preserving declared method calls across ESM and CJS. Branded class methods so custom function fields are rejected; type-only change, no runtime impact.

Description

Branded declared AxiosHeaders methods and typed them as properties to distinguish them from arbitrary functions.
Narrowed [key: string] to AxiosHeaderValueOrMethod in index.d.ts and index.d.cts so custom fields accept only header values; methods remain callable.
Added ESM/CJS type tests for custom fields: allow string/number/array; reject Promise and custom function assignments.
Docs: update /docs/ to list allowed custom header value types and note that promises/functions are not allowed.
Fixes typings bug (not type safety): class field type of AxiosHeaders => any #7487.

Semantic version impact

Patch: Type tightening only; may surface invalid TypeScript usages at compile time.

^{Written for commit d31a7a0. Summary will update on new commits. Review in cubic}

Narrow custom header field assignments to values axios accepts while keeping declared header methods callable. Constraint: Preserve declared AxiosHeaders methods while narrowing arbitrary string fields. Rejected: Keep the any index signature | It allows non-header values to type-check. Confidence: high Scope-risk: narrow Directive: Keep ESM and CJS declarations in sync for AxiosHeaders type changes. Tested: .\\node_modules\\.bin\\mocha --timeout 10000 tests\\typings.module.test.cjs (from tests/module/cjs) Tested: npx vitest run --config vitest.config.js --project module tests/typings.module.test.js (from tests/module/esm) Tested: npx prettier --check changed typing files Tested: git diff --check Not-tested: full test suite

cubic-dev-ai

1 issue found across 6 files

Confidence score: 4/5

This PR looks safe to merge with minimal risk: the reported issue is moderate (5/10) and focused on type constraints rather than a clear runtime break.
In index.d.cts, the AxiosHeaders string index still allows arbitrary function values, so custom header fields are not fully restricted to valid header value types.
The impact appears to be mostly TypeScript typing looseness (potentially weaker compile-time safety) rather than a concrete user-facing regression.
Pay close attention to index.d.cts - tighten the AxiosHeaders index signature so custom headers cannot accept arbitrary functions.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="index.d.cts">

<violation number="1" location="index.d.cts:13">
P2: The new `AxiosHeaders` string index type still permits arbitrary function values, so custom header fields are not fully constrained to header values.</violation>
</file>

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

Brand declared AxiosHeaders methods so the string index can accept the class API while custom header fields remain limited to AxiosHeaderValue. Constraint: The AxiosHeaders class needs a string index for custom headers and string-named methods on the same instance. Rejected: Keep a broad function index signature | It lets arbitrary custom header functions type-check. Confidence: high Scope-risk: narrow Directive: Keep ESM and CJS AxiosHeaders declarations aligned. Tested: .\node_modules\.bin\mocha --timeout 10000 tests\typings.module.test.cjs (from tests/module/cjs) Tested: npx vitest run --config vitest.config.js --project module tests/typings.module.test.js (from tests/module/esm) Tested: npx prettier --check index.d.ts index.d.cts tests/module/cjs/tests/helpers/headers-types.ts tests/module/esm/tests/helpers/headers-types.ts tests/module/cjs/tests/typings.module.test.cjs tests/module/esm/tests/typings.module.test.js Tested: git diff --check Not-tested: full test suite

LaplaceYoung · May 26, 2026

Updated in d31a7a0.

The AxiosHeaders index now accepts only header values plus branded declared method types, so custom header fields reject function assignments while the existing AxiosHeaders methods remain callable. Added CJS and ESM type fixtures covering function assignment with @ts-expect-error.

Checked:

./node_modules/.bin/mocha --timeout 10000 tests/typings.module.test.cjs from tests/module/cjs
npx vitest run --config vitest.config.js --project module tests/typings.module.test.js from tests/module/esm
npx prettier --check index.d.ts index.d.cts tests/module/cjs/tests/helpers/headers-types.ts tests/module/esm/tests/helpers/headers-types.ts tests/module/cjs/tests/typings.module.test.cjs tests/module/esm/tests/typings.module.test.js
git diff --check

jasonsaayman

We may need to hold off on this merge, but let's make these changes in the meantime. This would be a breaking change if it lands.

jasonsaayman · May 27, 2026

+export class AxiosHeaders {
+  constructor(headers?: RawAxiosHeaders | AxiosHeaders | string);
+
+  [key: string]: AxiosHeaderValueOrMethod;


Generated custom accessors from AxiosHeaders.accessor('X-Foo') are no longer callable by type because unknown keys resolve to AxiosHeaderValueOrMethod, a union with non-callable members. Add ESM and CJS type tests for setXFoo / getXFoo / hasXFoo, then preserve callable typings, likely with template-literal signatures for set${string}, get${string}, and has${string}.

jasonsaayman · May 27, 2026

@@ -0,0 +1,13 @@
+import { AxiosHeaders } from '../../../../index.js';
+
+const headers = new AxiosHeaders({ x: 1 });


Add positive assertions that declared methods still call correctly, not only negative custom-field assignments.

LaplaceYoung requested a review from jasonsaayman as a code owner May 24, 2026 05:21

cubic-dev-ai Bot reviewed May 24, 2026

View reviewed changes

Comment thread index.d.cts Outdated

jasonsaayman assigned LaplaceYoung May 24, 2026

jasonsaayman added priority::medium A medium priority commit::fix The PR is related to a bugfix labels May 24, 2026

jasonsaayman requested changes May 27, 2026

View reviewed changes

jasonsaayman added the status::changes-requested A reviewer requested changes to the PR label May 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(types): constrain AxiosHeaders custom fields#10941

fix(types): constrain AxiosHeaders custom fields#10941
LaplaceYoung wants to merge 2 commits into
axios:v1.xaxios/axios:v1.xfrom
LaplaceYoung:fix/axiosheaders-index-signatureLaplaceYoung/axios:fix/axiosheaders-index-signatureCopy head branch name to clipboard

LaplaceYoung commented May 24, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

Uh oh!

LaplaceYoung commented May 26, 2026

Uh oh!

jasonsaayman left a comment

Uh oh!

jasonsaayman May 27, 2026

Uh oh!

jasonsaayman May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Search code, repositories, users, issues, pull requests...

Uh oh!

Conversation

LaplaceYoung commented May 24, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tests

Summary by cubic

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LaplaceYoung commented May 26, 2026

Uh oh!

jasonsaayman left a comment

Choose a reason for hiding this comment

Uh oh!

jasonsaayman May 27, 2026

Choose a reason for hiding this comment

Uh oh!

jasonsaayman May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

LaplaceYoung commented May 24, 2026 •

edited by cubic-dev-ai Bot

Loading