@gcmdev/faxios 0.1.0 → 0.2.0

package/dist/lib/plugins/retry.js

@@ -0,0 +1,168 @@
+// @ts-self-types="./retry.d.ts" — required for Deno: maps built .js to adjacent .d.ts in dist/
+import CanceledError from "../cancel/CanceledError.js";
+import isCancel from "../cancel/isCancel.js";
+import FaxiosError from "../core/FaxiosError.js";
+import validator from "../helpers/validator.js";
+import utils from "../utils.js";
+import { RETRY_ATTEMPT } from "./attempt.js";
+import { definePlugin } from "./definePlugin.js";
+// Config values are read as own properties only (repo rule for possibly untrusted input).
+const ownValue = (source, key) => (utils.hasOwnProp(source, key) ? source[key] : undefined);
+const isWait = (ms) => typeof ms === "number" && Number.isFinite(ms) && ms >= 0;
+// An HTTP method is a token (RFC 9110 §9.1, §5.6.2); anything else can never match a request.
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const isStatus = (value) => Number.isInteger(value) && value >= 100 && value <= 599;
+// Bounded on purpose: NaN or Infinity would make a failing request loop forever.
+const optionsSchema = {
+    attempts: (value) => (Number.isInteger(value) && value >= 1) || "an integer of at least 1",
+    retryOn: validator.validators["function"],
+    delay: (value) => isWait(value) || typeof value === "function" || "a finite number of at least 0 or a function",
+    methods: (value) => (Array.isArray(value) && value.every(m => typeof m === "string" && TOKEN.test(m))) || "an array of HTTP method names",
+    statuses: (value) => (Array.isArray(value) && value.every(isStatus)) || "an array of HTTP status codes (100-599)",
+    maxRetryAfter: (value) => isWait(value) || "a finite number of milliseconds of at least 0",
+    maxDelay: (value) => isWait(value) || "a finite number of milliseconds of at least 0",
+    jitter: (value) => value === "full" || value === "none" || "\"full\" or \"none\"",
+    respectRetryAfter: validator.validators["boolean"],
+    onRetry: validator.validators["function"],
+};
+// Transient failures: timeout, rate limit, and server errors that may clear on their own. 501 and
+// 505 mean the server will never handle the request, so they aren't here.
+const DEFAULT_STATUSES = [408, 429, 500, 502, 503, 504];
+// Statuses whose Retry-After says when to try again (RFC 9110 §10.2.3).
+const RETRY_AFTER_STATUSES = [429, 503];
+// Methods whose repeat has the same effect as one request (RFC 9110 §9.2.2, plus QUERY).
+const IDEMPOTENT_METHODS = ["get", "head", "options", "put", "delete", "query"];
+// One check for both the factory argument and a per-request override.
+function assertRetryOptions(value, config) {
+    if (value === null || typeof value !== "object") {
+        throw new FaxiosError("retry options must be an object", FaxiosError.ERR_BAD_OPTION_VALUE, config);
+    }
+    validator.assertOptions(value, optionsSchema, false);
+}
+function retryByDefault(error, statuses) {
+    if (isCancel(error) || !(error instanceof FaxiosError))
+        return false;
+    if (error.code === FaxiosError.ERR_NETWORK || error.code === FaxiosError.ETIMEDOUT)
+        return true;
+    const status = error.response?.status;
+    return status !== undefined && statuses.includes(status);
+}
+// The wait a 429 or 503 asks for, in milliseconds: delay-seconds or an HTTP date (a past date
+// means now). undefined when there's no usable header, so the computed backoff applies.
+function retryAfterMs(error) {
+    if (!(error instanceof FaxiosError) || !error.response || !RETRY_AFTER_STATUSES.includes(error.response.status))
+        return undefined;
+    const value = error.response.headers.get("retry-after");
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    const date = Date.parse(trimmed);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+const doublingDelay = (attempt) => 100 * 2 ** (attempt - 1);
+// A stream is consumed by the first try, so sending it again would send nothing.
+// The same stream checks the fetch adapter uses: web ReadableStreams and Node-style pipe streams.
+function canReplay(data) {
+    return !utils.isReadableStream?.(data) && !utils.isStream(data);
+}
+function wait(ms, signal, config) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new CanceledError(null, config));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener?.("abort", onAbort);
+            reject(new CanceledError(null, config));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener?.("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener?.("abort", onAbort);
+    });
+}
+// Each list is lower-cased right after it is validated: the plugin's once, a per-request override's
+// on the request that carries it.
+function retriesMethod(config, perRequest, pluginMethods) {
+    const requestMethods = perRequest ? ownValue(perRequest, "methods")?.map(m => m.toLowerCase()) : undefined;
+    const methods = requestMethods ?? pluginMethods ?? IDEMPOTENT_METHODS;
+    return methods.includes(String(ownValue(config, "method") ?? "get").toLowerCase());
+}
+// Per field, request first: no merged object, and only own properties count.
+function resolvePolicy(options, perRequest) {
+    const setting = (key) => (perRequest ? ownValue(perRequest, key) : undefined) ?? ownValue(options, key);
+    const statuses = setting("statuses") ?? DEFAULT_STATUSES;
+    return {
+        attempts: setting("attempts") ?? 3,
+        retryOn: setting("retryOn") ?? ((error) => retryByDefault(error, statuses)),
+        delay: setting("delay") ?? doublingDelay,
+        maxDelay: setting("maxDelay") ?? 30_000,
+        jitter: setting("jitter") ?? "full",
+        maxRetryAfter: setting("maxRetryAfter") ?? 300_000,
+        respectRetryAfter: setting("respectRetryAfter") ?? true,
+        onRetry: setting("onRetry"),
+    };
+}
+// How long to wait before the next try, or undefined when the server's Retry-After is longer
+// than the caller is willing to wait, so the error is rethrown.
+function waitBeforeRetry(error, attempt, policy, config) {
+    const retryAfter = policy.respectRetryAfter ? retryAfterMs(error) : undefined;
+    if (retryAfter !== undefined)
+        return retryAfter > policy.maxRetryAfter ? undefined : retryAfter;
+    const computed = typeof policy.delay === "function" ? policy.delay(attempt, error) : policy.delay;
+    if (!isWait(computed)) {
+        throw new FaxiosError(`retry: delay must give a finite number of at least 0, got ${String(computed)}`, FaxiosError.ERR_BAD_OPTION_VALUE, config);
+    }
+    const capped = Math.min(computed, policy.maxDelay);
+    // Jitter only spreads out clients that failed together; it needs no unpredictability.
+    // eslint-disable-next-line sonarjs/pseudo-random -- see above
+    return policy.jitter === "full" ? Math.floor(Math.random() * capped) : capped;
+}
+/**
+ * Retries failed requests by calling `next` again. Each `next` dispatches its own copy of the
+ * config, so every try starts from the same input. Install it inside middleware that should run
+ * once per request (for example `timing` installed first measures all tries together).
+ */
+export function retry(options = {}) {
+    assertRetryOptions(options);
+    // Lower-cased once here, so requests compare names without re-casing the list.
+    const pluginMethods = ownValue(options, "methods")?.map(m => m.toLowerCase());
+    return definePlugin({
+        name: "retry",
+        middleware: async (ctx, next) => {
+            const perRequest = ownValue(ctx.config, "retry");
+            if (perRequest === false)
+                return next(ctx);
+            if (perRequest !== undefined)
+                assertRetryOptions(perRequest, ctx.config);
+            const policy = resolvePolicy(options, perRequest);
+            if (!retriesMethod(ctx.config, perRequest, pluginMethods))
+                return next(ctx);
+            // Tries run one after another on purpose: each must finish before deciding on the next.
+            for (let attempt = 1;; attempt++) {
+                // For timing: the try number, read after next() settles.
+                ctx.state[RETRY_ATTEMPT] = attempt;
+                try {
+                    // eslint-disable-next-line no-await-in-loop -- see above
+                    return await next(ctx);
+                }
+                catch (error) {
+                    if (attempt >= policy.attempts || !canReplay(ownValue(ctx.config, "data")) || !policy.retryOn(error, attempt))
+                        throw error;
+                    const ms = waitBeforeRetry(error, attempt, policy, ctx.config);
+                    if (ms === undefined)
+                        throw error;
+                    // A throwing hook rejects the request with its own error, before any wait.
+                    policy.onRetry?.(error, attempt, ms);
+                    // eslint-disable-next-line no-await-in-loop -- see above
+                    await wait(ms, ownValue(ctx.config, "signal"), ctx.config);
+                }
+            }
+        },
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/lib/plugins/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/lib/plugins/retry.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,OAAO,aAAa,mCAAmC;AACvD,OAAO,QAAQ,8BAA8B;AAC7C,OAAO,WAAW,+BAA+B;AACjD,OAAO,SAAS,gCAAgC;AAEhD,OAAO,KAAK,oBAAoB;AAChC,OAAO,EAAE,aAAa,EAAE,qBAAqB;AAC7C,OAAO,EAAE,YAAY,EAAE,0BAA0B;AAEjD,0FAA0F;AAC1F,MAAM,QAAQ,GAAG,CAAsC,MAAS,EAAE,GAAM,EAAoB,EAAE,CAC5F,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAE5D,MAAM,MAAM,GAAG,CAAC,EAAW,EAAgB,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAEvG,8FAA8F;AAC9F,MAAM,KAAK,GAAG,gCAAgC,CAAC;AAE/C,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,IAAI,GAAG,IAAK,KAAgB,IAAI,GAAG,CAAC;AAErH,iFAAiF;AACjF,MAAM,aAAa,GAAG;IACpB,QAAQ,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,IAAI,CAAC,CAAC,IAAI,0BAA0B;IAC/G,OAAO,EAAE,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC;IACzC,KAAK,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,UAAU,IAAI,6CAA6C;IACxH,OAAO,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,+BAA+B;IAClJ,QAAQ,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,yCAAyC;IAC1H,aAAa,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,+CAA+C;IACnG,QAAQ,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,+CAA+C;IAC9F,MAAM,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,MAAM,IAAI,sBAAsB;IAC1F,iBAAiB,EAAE,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC;IAClD,OAAO,EAAE,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC;CAC1C,CAAC;AAEF,kGAAkG;AAClG,0EAA0E;AAC1E,MAAM,gBAAgB,GAA0B,CAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAE,CAAC;AAEjF,wEAAwE;AACxE,MAAM,oBAAoB,GAA0B,CAAE,GAAG,EAAE,GAAG,CAAE,CAAC;AAEjE,yFAAyF;AACzF,MAAM,kBAAkB,GAA0B,CAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAE,CAAC;AAEzG,sEAAsE;AACtE,SAAS,kBAAkB,CAAC,KAAc,EAAE,MAAoC;IAC9E,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,IAAI,WAAW,CAAC,iCAAiC,EAAE,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACrG,CAAC;IACD,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC;AA0DD,SAAS,cAAc,CAAC,KAAc,EAAE,QAA+B;IACrE,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAChG,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;IACtC,OAAO,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED,8FAA8F;AAC9F,wFAAwF;AACxF,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClI,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,aAAa,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;AAEpE,iFAAiF;AACjF,kGAAkG;AAClG,SAAS,SAAS,CAAC,IAAa;IAC9B,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,IAAI,CAAC,EAAU,EAAE,MAAoD,EAAE,MAA2B;IACzG,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACxC,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,EAAE,mBAAmB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,CAAC,IAAI,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC1C,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChD,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,gBAAgB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,oGAAoG;AACpG,kCAAkC;AAClC,SAAS,aAAa,CAAC,MAAmC,EAAE,UAAoC,EAAE,aAAgD;IAChJ,MAAM,cAAc,GAAG,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3G,MAAM,OAAO,GAAG,cAAc,IAAI,aAAa,IAAI,kBAAkB,CAAC;IACtE,OAAO,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACrF,CAAC;AAaD,6EAA6E;AAC7E,SAAS,aAAa,CAAC,OAAqB,EAAE,UAAoC;IAChF,MAAM,OAAO,GAAG,CAA+B,GAAM,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACzI,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,gBAAgB,CAAC;IACzD,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QAClC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpF,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,aAAa;QACxC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,MAAM;QACvC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,MAAM;QACnC,aAAa,EAAE,OAAO,CAAC,eAAe,CAAC,IAAI,OAAO;QAClD,iBAAiB,EAAE,OAAO,CAAC,mBAAmB,CAAC,IAAI,IAAI;QACvD,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,gEAAgE;AAChE,SAAS,eAAe,CAAC,KAAc,EAAE,OAAe,EAAE,MAAc,EAAE,MAAmC;IAC3G,MAAM,UAAU,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;IAChG,MAAM,QAAQ,GAAY,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3G,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,WAAW,CAAC,6DAA6D,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACnJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnD,sFAAsF;IACtF,8DAA8D;IAC9D,OAAO,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,UAAwB,EAAE;IAC9C,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,+EAA+E;IAC/E,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9E,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,OAAO;QACb,UAAU,EAAE,KAAK,EAAE,GAAuC,EAAE,IAAI,EAAE,EAAE;YAClE,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACjD,IAAI,UAAU,KAAK,KAAK;gBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,UAAU,KAAK,SAAS;gBAAE,kBAAkB,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YACzE,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAClD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC;gBAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;YAE5E,wFAAwF;YACxF,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;gBAClC,yDAAyD;gBACzD,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC;gBACnC,IAAI,CAAC;oBACH,yDAAyD;oBACzD,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;gBACzB,CAAC;gBACD,OAAO,KAAK,EAAE,CAAC;oBACb,IAAI,OAAO,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;wBAAE,MAAM,KAAK,CAAC;oBAC3H,MAAM,EAAE,GAAG,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;oBAC/D,IAAI,EAAE,KAAK,SAAS;wBAAE,MAAM,KAAK,CAAC;oBAClC,2EAA2E;oBAC3E,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;oBACrC,yDAAyD;oBACzD,MAAM,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC7D,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/plugins/timing.d.ts

@@ -0,0 +1,31 @@
+import type { FaxiosPlugin } from "../types.js";
+/**
+ * What `timing` reports once per request: `status` on success, `error` on failure. No config,
+ * headers or body, so an event is safe to log.
+ */
+export type TimingEvent = {
+    /** The request method, upper-cased (`"GET"`). */
+    method: string;
+    /** The full request URL without its query string and fragment. */
+    url: string;
+    /**
+     * The try number from `retry`: each try's when installed after it, the final try's when
+     * installed before it. Absent without `retry`.
+     */
+    attempt?: number;
+    durationMs: number;
+} & ({
+    status: number;
+    error?: undefined;
+} | {
+    status?: undefined;
+    error: unknown;
+});
+/**
+ * Measures the time around `next` and calls `onTiming` once per request with the method, URL,
+ * duration and status or error. Installed before `retry`, the duration covers every try;
+ * installed after it, each try is reported. The response is returned unchanged. If `onTiming`
+ * throws while reporting a failure, the request still rejects with its own error; while
+ * reporting a success, its error rejects the request.
+ */
+export declare function timing(onTiming: (event: TimingEvent) => void): FaxiosPlugin;

package/dist/lib/plugins/timing.js

@@ -0,0 +1,53 @@
+// @ts-self-types="./timing.d.ts" — required for Deno: maps built .js to adjacent .d.ts in dist/
+import buildFullPath from "../core/buildFullPath.js";
+import utils from "../utils.js";
+import { RETRY_ATTEMPT } from "./attempt.js";
+import { definePlugin } from "./definePlugin.js";
+const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+const own = (source, key) => (utils.hasOwnProp(source, key) ? source[key] : undefined);
+// Read once the request settles, so a later middleware's changes to the config count. The query
+// and fragment often carry secrets, and they'd make every URL a different metric label.
+function describe({ config, state }) {
+    // Typed string, but undefined when the request has neither url nor baseURL.
+    const full = buildFullPath(own(config, "baseURL"), own(config, "url"), own(config, "allowAbsoluteUrls"));
+    const url = typeof full === "string" ? full : "";
+    const end = url.search(/[?#]/);
+    const attempt = state[RETRY_ATTEMPT];
+    return {
+        method: String(own(config, "method") ?? "get").toUpperCase(),
+        url: end === -1 ? url : url.slice(0, end),
+        ...(typeof attempt === "number" ? { attempt } : {}),
+    };
+}
+/**
+ * Measures the time around `next` and calls `onTiming` once per request with the method, URL,
+ * duration and status or error. Installed before `retry`, the duration covers every try;
+ * installed after it, each try is reported. The response is returned unchanged. If `onTiming`
+ * throws while reporting a failure, the request still rejects with its own error; while
+ * reporting a success, its error rejects the request.
+ */
+export function timing(onTiming) {
+    return definePlugin({
+        name: "timing",
+        middleware: async (ctx, next) => {
+            const start = now();
+            let response;
+            try {
+                response = await next(ctx);
+            }
+            catch (error) {
+                try {
+                    onTiming({ ...describe(ctx), durationMs: now() - start, error });
+                }
+                catch {
+                    // The request's own error matters more than the observer's; keep it.
+                }
+                throw error;
+            }
+            // Outside the try, so an onTiming that throws isn't reported as a failed request.
+            onTiming({ ...describe(ctx), durationMs: now() - start, status: response.status });
+            return response;
+        },
+    });
+}
+//# sourceMappingURL=timing.js.map

package/dist/lib/plugins/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../../src/lib/plugins/timing.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,OAAO,aAAa,iCAAiC;AAErD,OAAO,KAAK,oBAAoB;AAChC,OAAO,EAAE,aAAa,EAAE,qBAAqB;AAC7C,OAAO,EAAE,YAAY,EAAE,0BAA0B;AAmBjD,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,OAAO,WAAW,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;AAExF,MAAM,GAAG,GAAG,CAAsC,MAAS,EAAE,GAAM,EAAoB,EAAE,CACvF,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAE5D,gGAAgG;AAChG,wFAAwF;AACxF,SAAS,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,EAAiB;IAChD,4EAA4E;IAC5E,MAAM,IAAI,GAAY,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAClH,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IACrC,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE;QAC5D,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QACzC,GAAG,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,QAAsC;IAC3D,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC;YACpB,IAAI,QAAQ,CAAC;YACb,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,CAAC;oBACH,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,CAAC;gBACD,MAAM,CAAC;oBACL,qEAAqE;gBACvE,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,kFAAkF;YAClF,QAAQ,CAAC,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACnF,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/types.d.ts

@@ -1,3 +1,4 @@
+import type { FaxiosHeadersInstance } from "./core/FaxiosHeaders.js";
 import type { StandardSchemaV1 } from "./types/standard-schema.js";
 export type StringLiteralsOrString<Literals extends string> = Literals | (string & {});
 export type FaxiosHeaderValue = string | Array<string> | number | boolean | null;
@@ -6,13 +7,25 @@ export interface RawFaxiosHeaders {
 }
 type UppercaseMethod = "GET" | "DELETE" | "HEAD" | "OPTIONS" | "POST" | "PUT" | "PATCH" | "PURGE" | "LINK" | "UNLINK" | "QUERY";
 export type Method = UppercaseMethod | Lowercase<UppercaseMethod>;
-type CommonRequestHeadersList = "Accept" | "Content-Length" | "User-Agent" | "Content-Encoding" | "Authorization" | "Location";
-type ContentType = FaxiosHeaderValue | "text/html" | "text/plain" | "multipart/form-data" | "application/json" | "application/x-www-form-urlencoded" | "application/octet-stream";
-export type RawFaxiosRequestHeaders = Partial<RawFaxiosHeaders & {
-    [Key in CommonRequestHeadersList]: FaxiosHeaderValue;
+type CommonRequestHeadersList = "Accept" | "Accept-Encoding" | "Accept-Language" | "Authorization" | "Cache-Control" | "Content-Encoding" | "Content-Length" | "If-Match" | "If-Modified-Since" | "If-None-Match" | "Range" | "User-Agent" | "X-Requested-With";
+type ContentType = StringLiteralsOrString<"text/html" | "text/plain" | "multipart/form-data" | "application/json" | "application/x-www-form-urlencoded" | "application/octet-stream" | "application/problem+json" | "application/ld+json" | "text/event-stream" | "application/graphql-response+json" | "application/merge-patch+json" | "application/json-patch+json"> | Exclude<FaxiosHeaderValue, string>;
+/**
+ * A header bag: header names mapped to header values. Any header name is
+ * accepted in any casing; common names and `Content-Type` values are suggested.
+ *
+ * - Strings, numbers and string arrays are sent (numbers and `true` as strings).
+ * - `undefined` drops a value inherited from defaults or an outer config;
+ *   faxios may still set its own value (e.g. `Content-Type` for a JSON body).
+ * - `null` or `false` keeps the header off the request entirely; faxios does
+ *   not fill it in, and later merges keep it off unless they force an overwrite.
+ */
+export type RawFaxiosRequestHeaders = {
+    [header: string]: FaxiosHeaderValue | undefined;
 } & {
-    "Content-Type": ContentType;
-}>;
+    [Header in CommonRequestHeadersList]?: FaxiosHeaderValue;
+} & {
+    "Content-Type"?: ContentType;
+};
 export type ResponseType = "arraybuffer" | "blob" | "document" | "json" | "text" | "stream" | "formdata" | "response";
 type UppercaseResponseEncoding = "ASCII" | "ANSI" | "BINARY" | "BASE64" | "BASE64URL" | "HEX" | "LATIN1" | "UCS-2" | "UCS2" | "UTF-8" | "UTF8" | "UTF16LE";
 export type responseEncoding = UppercaseResponseEncoding | Lowercase<UppercaseResponseEncoding>;
@@ -20,7 +33,6 @@ export interface TransitionalOptions {
     silentJSONParsing?: boolean;
     forcedJSONParsing?: boolean;
     clarifyTimeoutError?: boolean;
-    legacyInterceptorReqResOrdering?: boolean;
     advertiseZstdAcceptEncoding?: boolean;
     validateStatusUndefinedResolves?: boolean;
 }
@@ -51,10 +63,12 @@ export interface SerializerOptions {
     dots?: boolean;
     metaTokens?: boolean;
     indexes?: boolean | null;
+    /** Maximum nesting depth to serialize; deeper objects throw `ERR_FORM_DATA_DEPTH_EXCEEDED`. `Infinity` disables the check. */
+    maxDepth?: number;
 }
 export type FormSerializerOptions = SerializerOptions;
 export interface ParamEncoder {
-    (value: unknown, defaultEncoder: (value: unknown) => unknown): unknown;
+    (value: string, defaultEncoder: (value: string) => string): string;
 }
 export interface CustomParamsSerializer {
     (params: Record<string, unknown>, options?: ParamsSerializerOptions): string;
@@ -82,10 +96,9 @@ export interface FaxiosBasicCredentials {
     password: string;
 }
 type HeaderMatcher = string | RegExp | ((value: string, name: string) => boolean);
-type HeaderRewrite = boolean | ((value: string, name: string) => boolean);
 type HeaderGetResult = string | Array<string> | Record<string, string> | RegExpExecArray | true | null | undefined;
 export type FaxiosRequestHeaders = Record<string, FaxiosHeaderValue> & {
-    set: (header: string | Record<string, unknown>, value?: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
+    set: (header: string | Record<string, unknown>, value?: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
     get: (header: string, parser?: boolean | RegExp) => HeaderGetResult;
     has: (header: string, matcher?: HeaderMatcher) => boolean;
     delete: (header: string | Array<string>, matcher?: HeaderMatcher) => boolean;
@@ -93,22 +106,22 @@ export type FaxiosRequestHeaders = Record<string, FaxiosHeaderValue> & {
     normalize: (format?: boolean) => FaxiosRequestHeaders;
     concat: (...targets: Array<unknown>) => FaxiosRequestHeaders;
     getContentType: (matcher?: HeaderMatcher) => HeaderGetResult;
-    setContentType: (value: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
+    setContentType: (value: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
     hasContentType: (matcher?: HeaderMatcher) => boolean;
     getContentLength: (matcher?: HeaderMatcher) => HeaderGetResult;
-    setContentLength: (value: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
+    setContentLength: (value: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
     hasContentLength: (matcher?: HeaderMatcher) => boolean;
     getAccept: (matcher?: HeaderMatcher) => HeaderGetResult;
-    setAccept: (value: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
+    setAccept: (value: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
     hasAccept: (matcher?: HeaderMatcher) => boolean;
+    getAcceptEncoding: (matcher?: HeaderMatcher) => HeaderGetResult;
+    setAcceptEncoding: (value: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
+    hasAcceptEncoding: (matcher?: HeaderMatcher) => boolean;
     getUserAgent: (matcher?: HeaderMatcher) => HeaderGetResult;
-    setUserAgent: (value: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
+    setUserAgent: (value: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
     hasUserAgent: (matcher?: HeaderMatcher) => boolean;
-    getContentEncoding: (matcher?: HeaderMatcher) => HeaderGetResult;
-    setContentEncoding: (value: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
-    hasContentEncoding: (matcher?: HeaderMatcher) => boolean;
     getAuthorization: (matcher?: HeaderMatcher) => HeaderGetResult;
-    setAuthorization: (value: FaxiosHeaderValue, rewrite?: HeaderRewrite) => FaxiosRequestHeaders;
+    setAuthorization: (value: FaxiosHeaderValue, rewrite?: boolean) => FaxiosRequestHeaders;
     hasAuthorization: (matcher?: HeaderMatcher) => boolean;
     toJSON: (asStrings?: boolean) => Record<string, FaxiosHeaderValue>;
 };
@@ -125,7 +138,7 @@ export interface FaxiosRequestConfig<D = unknown> {
     allowAbsoluteUrls?: boolean;
     transformRequest?: FaxiosRequestTransformer | Array<FaxiosRequestTransformer>;
     transformResponse?: FaxiosResponseTransformer | Array<FaxiosResponseTransformer>;
-    headers?: Record<string, unknown>;
+    headers?: FaxiosConfigHeaders;
     params?: Record<string, unknown> | URLSearchParams;
     paramsSerializer?: ParamsSerializerOptions | CustomParamsSerializer;
     data?: D;
@@ -145,10 +158,12 @@ export interface FaxiosRequestConfig<D = unknown> {
     transitional?: TransitionalOptions;
     signal?: AbortSignal | GenericAbortSignal;
     env?: {
-        FormData?: new (...args: Array<unknown>) => object;
+        /** Constructed with no arguments to serialize `multipart/form-data` payloads; `null` falls back to the global `FormData`. */
+        FormData?: (new () => object) | null;
         fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-        Request?: new (input: string | URL | Request, init?: RequestInit) => unknown;
-        Response?: new (...args: Array<unknown>) => unknown;
+        /** `null` disables the constructor, e.g. when a custom `fetch` is incompatible with the global one. */
+        Request?: (new (input: string | URL | Request, init?: RequestInit) => unknown) | null;
+        Response?: (new (...args: Array<unknown>) => unknown) | null;
     };
     formSerializer?: FormSerializerOptions;
     withXSRFToken?: boolean | ((config: InternalFaxiosRequestConfig) => boolean | undefined);
@@ -201,19 +216,83 @@ export interface HeadersDefaults {
 export interface FaxiosDefaults<D = unknown> extends Omit<FaxiosRequestConfig<D>, "headers"> {
     headers: HeadersDefaults;
 }
-export interface CreateFaxiosDefaults<D = unknown> extends Omit<FaxiosRequestConfig<D>, "headers"> {
-    headers?: RawFaxiosRequestHeaders | Partial<HeadersDefaults>;
+/**
+ * The `headers` option on every request config and on `create()`: a header
+ * bag, method header groups (a header bag under `common` or a method name,
+ * applied only to requests with that method), both mixed in one object, or a
+ * `FaxiosHeaders` instance.
+ */
+export type FaxiosConfigHeaders = RawFaxiosRequestHeaders | Partial<HeadersDefaults> | FaxiosHeadersInstance;
+/** Config accepted by `create()`; identical to a request config. */
+export type CreateFaxiosDefaults<D = unknown> = FaxiosRequestConfig<D>;
+interface ContextHeaders {
+    get headers(): FaxiosRequestHeaders;
+    set headers(value: FaxiosRequestHeaders | FaxiosHeadersInstance);
 }
-export interface FaxiosInterceptorOptions {
-    synchronous?: boolean;
-    runWhen?: ((config: InternalFaxiosRequestConfig) => boolean) | null;
+/**
+ * Per-request state passed through `.use()` middleware. Created once per
+ * request, after the request config is merged with the instance defaults.
+ */
+export interface FaxiosContext<TOptions = {}, TCapabilities = {}> {
+    /** The merged request config. `headers` is a `FaxiosHeaders` instance. */
+    config: Omit<InternalFaxiosRequestConfig, "headers"> & ContextHeaders & TOptions;
+    /** Null-prototype scratch space shared by middleware for this request only. */
+    state: Record<PropertyKey, unknown>;
+    /** Values provided by installed plugins, shared by every request of the instance. */
+    capabilities: TCapabilities;
 }
-export type FaxiosInterceptorFulfilled<T> = (value: T) => T | Promise<T>;
-export type FaxiosInterceptorRejected = (error: unknown) => unknown;
-export interface FaxiosInterceptorHandler<T> {
-    fulfilled: FaxiosInterceptorFulfilled<T>;
-    rejected?: FaxiosInterceptorRejected;
-    synchronous: boolean;
-    runWhen?: ((config: InternalFaxiosRequestConfig) => boolean) | null;
+/**
+ * Runs the rest of the middleware chain, then dispatches a copy of `ctx.config`. It takes the same
+ * context type the middleware received, so a middleware can't pass on fewer capabilities or
+ * options than later middleware expects.
+ */
+export type FaxiosNext<TOptions = {}, TCapabilities = {}> = (ctx: FaxiosContext<TOptions, TCapabilities>) => Promise<FaxiosResponse>;
+/**
+ * Onion-style lifecycle hook: code before `await next(ctx)` runs on the way in,
+ * code after it on the way out. Returning without calling `next` skips dispatch.
+ */
+export type FaxiosMiddleware<TOptions = {}, TCapabilities = {}> = (ctx: FaxiosContext<TOptions, TCapabilities>, next: FaxiosNext<TOptions, TCapabilities>) => Promise<FaxiosResponse>;
+/**
+ * The type slots of a `FaxiosPlugin`, all optional: `requires` holds the capabilities that must be
+ * installed before it, `provides` the capabilities it adds to `ctx.capabilities`, and `options`
+ * the request options it adds to every config-taking member.
+ */
+export interface FaxiosPluginSpec {
+    requires?: unknown;
+    provides?: unknown;
+    options?: unknown;
 }
+type PluginSlot<TSpec, K extends keyof FaxiosPluginSpec> = K extends keyof TSpec ? Required<TSpec>[K] : unknown;
+type OnlyPluginSlots<TSpec> = {
+    [K in Exclude<keyof TSpec, keyof FaxiosPluginSpec>]: never;
+};
+/**
+ * The parts of a plugin that `use()` reads its type parameters from. Internal: build plugins with
+ * `definePlugin()` or annotate them as `FaxiosPlugin`; `use()` infers `TRequires`, `TProvides`
+ * and `TOptions` through this.
+ */
+export interface FaxiosPluginBase<TRequires = unknown, TProvides = unknown, TOptions = unknown> {
+    name: string;
+    middleware: FaxiosMiddleware<TOptions, TRequires & TProvides>;
+    /** Internal, type-only marker that carries the type parameters for inference. Never set it. */
+    readonly "~plugin"?: {
+        readonly requires: TRequires;
+        readonly provides: TProvides;
+        readonly options: TOptions;
+    };
+}
+/**
+ * Middleware bundled with the capabilities it requires and provides, typed by one
+ * `FaxiosPluginSpec`: `FaxiosPlugin<{ requires?; provides?; options? }>`. Declaring `provides`
+ * makes the `provides` value required, so a plugin can't claim a capability it never supplies.
+ */
+export type FaxiosPlugin<TSpec extends FaxiosPluginSpec & OnlyPluginSlots<TSpec> = {}> = FaxiosPluginBase<PluginSlot<TSpec, "requires">, PluginSlot<TSpec, "provides">, PluginSlot<TSpec, "options">> & ([keyof PluginSlot<TSpec, "provides">] extends [never] ? {
+    provides?: PluginSlot<TSpec, "provides">;
+} : {
+    provides: PluginSlot<TSpec, "provides">;
+});
+/** What `use()` and `eject()` accept as a plugin: the base plus an optional `provides`. Internal. */
+export type FaxiosPluginArgument<TRequires = unknown, TProvides = unknown, TOptions = unknown> = FaxiosPluginBase<TRequires, TProvides, TOptions> & {
+    provides?: TProvides;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcmdev/faxios",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Promise based, web-standard fetch HTTP client for the browser, Node.js, Deno and Bun",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -17,7 +17,8 @@
     "browser",
     "rest",
     "api",
-    "client"
+    "client",
+    "tanstack-intent"
   ],
   "author": "Adrian Elton-Browning",
   "contributors": [
@@ -40,20 +41,37 @@
   "bugs": {
     "url": "https://github.com/adrianbrowning/faxios/issues"
   },
-  "homepage": "https://faxios-http.com",
+  "homepage": "https://adrianbrowning.github.io/faxios/",
   "files": [
-    "dist/"
+    "dist/",
+    "skills/configure-requests"
   ],
+  "scripts": {
+    "build": "zshy",
+    "bp": "pnpm build && pnpm pack",
+    "version": "pnpm run build && git add package.json",
+    "docs:dev": "cd docs && npm run docs:dev",
+    "lint": "pnpm lint:ts && pnpm lint:esl && pnpm lint:fix",
+    "lint:ts": "tsc --noEmit -p tsconfig.check.json",
+    "lint:esl": "eslint --config eslint.config.ts \"**/*.{j,t}s{,x}\" --cache --cache-strategy content --max-warnings=0",
+    "lint:s": "eslint --config eslint.config.style.ts \"**/*.{j,t}s{,x}\" --cache --cache-strategy content --max-warnings=0",
+    "lint:fix": "pnpm lint:s --fix",
+    "lint:e18e": "pnpm dlx @e18e/cli analyze"
+  },
   "devDependencies": {
-    "@gingacodemonkey/config": "^0.0.36",
+    "@gingacodemonkey/config": "^0.0.38",
     "eslint": "^9.39.4",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.62.1",
+    "typescript-eslint": "^8.71.0",
     "zshy": "latest"
   },
   "zshy": {
     "exports": {
       ".": "./src/index.ts",
+      "./plugins": "./src/lib/plugins/definePlugin.ts",
+      "./plugins/auth-bearer": "./src/lib/plugins/authBearer.ts",
+      "./plugins/retry": "./src/lib/plugins/retry.ts",
+      "./plugins/timing": "./src/lib/plugins/timing.ts",
       "./unsafe/core/buildFullPath.js": "./src/lib/core/buildFullPath.ts",
       "./unsafe/helpers/isAbsoluteURL.js": "./src/lib/helpers/isAbsoluteURL.ts",
       "./unsafe/helpers/buildURL.js": "./src/lib/helpers/buildURL.ts",
@@ -73,6 +91,22 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./plugins": {
+      "types": "./dist/lib/plugins/definePlugin.d.ts",
+      "default": "./dist/lib/plugins/definePlugin.js"
+    },
+    "./plugins/auth-bearer": {
+      "types": "./dist/lib/plugins/authBearer.d.ts",
+      "default": "./dist/lib/plugins/authBearer.js"
+    },
+    "./plugins/retry": {
+      "types": "./dist/lib/plugins/retry.d.ts",
+      "default": "./dist/lib/plugins/retry.js"
+    },
+    "./plugins/timing": {
+      "types": "./dist/lib/plugins/timing.d.ts",
+      "default": "./dist/lib/plugins/timing.js"
+    },
     "./unsafe/core/buildFullPath.js": {
       "types": "./dist/lib/core/buildFullPath.d.ts",
       "default": "./dist/lib/core/buildFullPath.js"
@@ -94,17 +128,5 @@
       "default": "./dist/lib/utils.js"
     },
     "./package.json": "./package.json"
-  },
-  "scripts": {
-    "build": "zshy",
-    "bp": "pnpm build && pnpm pack",
-    "version": "pnpm run build && git add package.json",
-    "docs:dev": "cd docs && npm run docs:dev",
-    "lint": "pnpm lint:ts; pnpm lint:fix",
-    "lint:ts": "tsc --noEmit -p tsconfig.check.json",
-    "lint:esl": "eslint --config eslint.config.ts \"**/*.{j,t}s{,x}\" --cache --cache-strategy content --max-warnings=0",
-    "lint:s": "eslint --config eslint.config.style.ts \"**/*.{j,t}s{,x}\" --cache --cache-strategy content --max-warnings=0",
-    "lint:fix": "pnpm lint:s --fix",
-    "lint:e18e": "pnpm dlx @e18e/cli analyze"
   }
-}
+}