axios — copilot-instructions.md

# GitHub Copilot Instructions

The canonical contributor guide for this repo is [`AGENTS.md`](../AGENTS.md). It covers setup, commands, package shape, architecture boundaries, naming, error handling, interceptor order, the request lifecycle, cancellation, common pitfalls, tests, and security-sensitive code.

The rules below are a Copilot-facing subset of the load-bearing safety guarantees from `AGENTS.md`. If they ever drift, `AGENTS.md` is authoritative — update both.

## Setup safety

- Install with `npm ci`; the repo's `.npmrc` sets `ignore-scripts=true`. Do not remove that flag. If husky hooks are needed after a fresh install, run `npm rebuild husky && npx husky` once.
- Do not add new runtime dependencies without discussion. `package-lock.json` is verified by `lockfile-lint` for npm HTTPS hosts and integrity hashes.

## Architecture in one screen

- `lib/core/` — domain logic: `Axios`, `AxiosError`, `AxiosHeaders`, `InterceptorManager`, config merge, request dispatch.
- `lib/adapters/` — I/O: `xhr.js`, `http.js`, `fetch.js`. Default preference `['xhr', 'http', 'fetch']`, picked by capability detection in `lib/adapters/adapters.js`. Never branch on environment name.
- `lib/platform/` — Node by default; browser builds alias to `lib/platform/browser`.
- `lib/helpers/` — generic, reusable utilities; no axios-specific lifecycle logic here.
- Source is ESM (`type: module`) with explicit `.js` import extensions. `dist/` is generated by Rollup — never edit it by hand. Keep `index.d.ts` (ESM) and `index.d.cts` (CJS) in sync for any public API change.

## Error handling

- Throw `AxiosError(message, code, config, request, response)` for axios-originated failures; never raw `Error`.
- Wrap third-party errors with `AxiosError.from(error, code, config, request, response)`.
- Use a code from `lib/core/AxiosError.js` (`ERR_NETWORK`, `ETIMEDOUT`, `ECONNABORTED`, `ERR_CANCELED`, `ERR_BAD_REQUEST`, `ERR_BAD_RESPONSE`, `ERR_FR_TOO_MANY_REDIRECTS`, `ERR_FORM_DATA_DEPTH_EXCEEDED`, `ERR_INVALID_URL`, `ERR_BAD_OPTION`, `ERR_BAD_OPTION_VALUE`, `ERR_NOT_SUPPORT`, `ERR_DEPRECATED`, `ECONNREFUSED`).

## Interceptor order

- Request interceptors run **LIFO** (last-registered-first); response interceptors run **FIFO**. Both support `synchronous: true` and `runWhen(config)`.

## Naming and style

- PascalCase classes (`Axios`, `AxiosHeaders`), camelCase functions (`buildURL`, `mergeConfig`), UPPER_SNAKE_CASE error codes.
- Internal slots use `Symbol`-keyed properties (see `$internals` in `lib/core/AxiosHeaders.js`), not underscore-prefixed names.
- Use `lib/helpers/bind.js`, not `Function.prototype.bind`, when binding library functions — the helper forwards `arguments` via `apply`.
- `'use strict';` appears at the top of files that already use it; match the surrounding file rather than blanket-adding it.

## Security guarantees that must not regress

- For config reads on potentially untrusted input, use own-property checks (`utils.hasOwnProp` / local `own()` helpers); never `in`, destructuring, or direct `config.foo` access.
- Any merge or object materialization must continue to filter `__proto__`, `constructor`, and `prototype`. Regressions here are security bugs.
- Changes touching URL construction, redirects, proxy/env handling, XSRF, socket paths, decompression limits, or adapters require consulting `THREATMODEL.md` and adding focused regression tests.
- `withXSRFToken === true` is the only thing that forces cross-origin XSRF header attachment — keep that behavior explicit.
- Do not weaken `beforeRedirect`, proxy, or `socketPath` safeguards without tests covering credential leakage and SSRF-style cases.

## Common pitfalls

- Do not mutate config objects in place; return new ones from merges/transforms.
- Do not assume browser- or Node-only globals exist; capability-check first.
- Validate options through the existing `validator` helper rather than inventing ad-hoc validation paths.