Interface RequestOptions

Opt-in partial-success mode for multi-field GraphQL documents. When set, a GraphQL envelope that carries both a non-null data object and a non-empty errors array resolves with the data instead of throwing AniLinkGraphQLError: the resolved fields are returned inline and the error entries are reported through the onError hook (with the normalized AniLinkGraphQLError as the hook's error argument) so failures stay observable. Envelopes with errors and no usable data still throw. "Usable" means at least one resolved (non-null) root field, so data: {} and data: { Media: null } (the GraphQL shape for a failed nullable root field) both throw. The resolution is terminal: the data is returned, never retried. But availability-class partial errors (429/5xx) still advance the circuit breaker the same way the strict mode's throw would. Off by default: every operation keeps the strict all-or-nothing behavior unless the caller opts in per request.

Skip the RequestOptions.responseCache for this one request: the read goes to the network even when a fresh cached entry exists, and the response is not written back. For reads whose freshness is the point, a watcher poll or a manual refresh, a cache hit would silently serve stale data. The instance-level cache still applies to every other request. Defaults to false.

Opt into a per-client circuit breaker for sustained upstream outages: after threshold consecutive failed attempts, further requests fail fast with a CIRCUIT_OPEN_ERROR network error until cooldownMs has elapsed since the last failure, after which the next request is allowed through as a probe. Each consecutive failed probe doubles the next cooldown (capped at eight times cooldownMs), so a recovering-but-slow upstream is probed on a widening schedule instead of being starved at one request per cooldown; a successful probe resets the scale. Off by default; when unset, no failure accounting happens across requests.

Controls how the library's two unsolicited diagnostics (a throwing lifecycle hook with no onHookError observer, and the one-time stateOwner keying warning) are emitted. "warn" (default) keeps the onHookError-with-console-fallback behavior; "hook" routes through onHookError only and never touches the console; "silent" suppresses both. See DiagnosticsMode.

Attach the original Axios error to thrown errors as rawAxiosError (and cause) for local debugging. Defaults to false because raw errors can contain request configuration and bearer-token headers.

Bypass the shared rate-limit pacing deadline recorded by a prior successful response to the same host, so an urgent single request (for example a user-facing lookup during a rate-limited window) is not held hostage by a deadline recorded from an earlier bulk request on the same client. Defaults to false; the per-request signal is still honored.

Upper bound on retained idle keep-alive sockets for this request. Defaults to MAX_FREE_SOCKETS (5); see RequestOptions.maxSockets.

Upper bound on concurrent keep-alive sockets for this request. Defaults to MAX_SOCKETS (20). Supplying this or maxFreeSockets constructs dedicated per-request agents instead of reusing the shared module-level pool, isolating this caller's socket pressure from other AniLink instances and providers.

Invoked when the circuit breaker closes (returns to healthy) after a successful post-cooldown probe, so consumers can plot open duration and recovery without inferring it from error-code absence.

Invoked when the circuit breaker opens (trips) after the consecutive-failure threshold is reached. Carries the host scope and the failure count so consumers can plot trip frequency and alert on sustained outages without parsing CIRCUIT_OPEN_ERROR codes.

Invoked when a user-supplied lifecycle hook throws. Throwing hooks are always isolated from the request pipeline; this callback observes the failure so it can be routed to a logger or metrics backend. When unset, hook failures are reported via console.warn.

Invoked when proactive rate-limit pacing (RequestOptions.paceWithRateLimit) delays the next request after a successful attempt, with the pacing wait in delayMs.

Invoked just before each attempt is sent.

Invoked after each attempt completes with the elapsed durationMs and the parsed rateLimit headers when present.

Invoked before each retry wait with the scheduled delay in nextDelayMs. Falls back to per-attempt onError calls when unset.

Opt into proactive request pacing driven by the x-ratelimit-* headers of every successful response: when the reported remaining quota drops below rateLimitFloor (default 1), the next attempt waits until the window resets instead of discovering the limit via a 429. On by default; pass false to disable it and discover the limit reactively (each 429 then costs a wasted request plus a retry wait).

Remaining-quota threshold below which RequestOptions.paceWithRateLimit delays the next request until the window resets. Defaults to 1. Must be a finite, non-negative integer; 0 disables floor-based pacing (the transport still honors Retry-After on 429 responses), and a defined-but-invalid value throws instead of being silently coerced.

Opt-in in-memory TTL response cache for read-heavy traversals. When set, cacheable reads are cached by (method, url, serialized body) for the cache's TTL window so repeated identical reads skip the network round-trip entirely. Cacheable reads are GET requests and GraphQL query documents (which the transport dispatches as POST); mutations, GraphQL mutation documents and REST POST/PUT/DELETE calls, are never cached. Off by default; pass a ResponseCache instance to enable.

Privacy: the cache retains the full response body of every cached read in plaintext for the TTL window, including authenticated user-scoped responses. Entries are scoped by a hash of the bearer token so they never cross identities, but within one identity sensitive payloads are retained. Do not enable for clients that fetch private user data unless the TTL is short and the cache instance is not shared across trust boundaries.

Automatic retries for transient failures. Defaults to the built-in policy (maxRetries: 3, jittered exponential backoff over HTTP 429 and 5xx responses plus network and timeout errors). Pass false to opt out and send every request exactly once, or pass a partial policy to tune individual knobs on top of the defaults.

Optional per-window cap on total retry attempts, complementing the per-request maxRetries and the opt-in circuitBreaker: the retry policy bounds one request's retries, the breaker handles sustained outages after consecutive failures, and this budget bounds the total retry spend across many requests in a rolling window (which handles chronic intermittent failures even when the breaker never trips). When the budget for the current window is exhausted, failures surface without retries until the window elapses. Off by default.

Signal used to cancel in-flight requests.

Milliseconds before a request is aborted. 0 disables the Axios timeout. Defaults to DEFAULT_REQUEST_TIMEOUT; timeout errors carry the effective duration as AniLinkNetworkError.timeoutMs.