@gcmdev/faxios 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcmdev/faxios",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Promise based, web-standard fetch HTTP client for the browser, Node.js, Deno and Bun",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -52,7 +52,7 @@
     "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": "pnpm lint:ts && pnpm lint:esl && pnpm lint:s",
     "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",
@@ -60,8 +60,8 @@
     "lint:e18e": "pnpm dlx @e18e/cli analyze"
   },
   "devDependencies": {
-    "@gingacodemonkey/config": "^0.0.38",
-    "eslint": "^9.39.4",
+    "@gingacodemonkey/config": "^0.1.0",
+    "eslint": "^9.39.5",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.0",
     "zshy": "latest"
@@ -129,5 +129,8 @@
       "default": "./dist/lib/utils.js"
     },
     "./package.json": "./package.json"
+  },
+  "imports": {
+    "#src/*.ts": "./src/*.ts"
   }
 }

package/skills/configure-requests/SKILL.md

@@ -86,8 +86,8 @@ const res = await faxios.get("https://api.example.com/users/{id}/posts", {
 // GET https://api.example.com/users/42/posts?page=2&tag=news
 ```
 
-`pathParams` values are `encodeURIComponent`-encoded. A missing or `null` value rejects with
-`ERR_BAD_OPTION_VALUE`.
+`pathParams` values are `encodeURIComponent`-encoded. A missing or `null` value, or `.`/`..`
+(also percent-encoded, such as `%2e%2e`), rejects with `ERR_BAD_OPTION_VALUE`.
 
 Binary downloads need `responseType`, and a type argument because `data` is `unknown`:
 
@@ -202,6 +202,9 @@ catch (error) {
   schema step and right before `fetch`, so an abort during pre-flight work sends nothing.
 - A timeout always rejects with `ETIMEDOUT`. `ECONNABORTED` is never raised, and
   `transitional.clarifyTimeoutError` has no effect.
+- With `responseType: "stream"`, `timeout` and `signal` stay active until the body is fully
+  read or cancelled. Reading a stalled body rejects with `ETIMEDOUT` or `ERR_CANCELED`.
+  Cancel a body you don't read so the timer and signal listener are released.
 
 ### Handle errors by code
 
@@ -273,6 +276,7 @@ plugin's request options (such as `retry: false`). Before writing plugin code, r
   `baseURL` origin when `baseURL` is absolute; otherwise only to relative request URLs. Use
   `origins` to allow more. It leaves an explicit `Authorization` header alone unless
   `overwrite: true`. Install `retry` before it if each attempt should call `getToken` again.
+  A `getToken` result that isn't a non-empty string sends the request without the header.
 - `retry` defaults: 3 attempts, statuses 408/429/500/502/503/504 plus `ERR_NETWORK` and
   `ETIMEDOUT`, exponential backoff from 100 ms with full jitter. A 429/503 `Retry-After` sets the
   wait unless `respectRetryAfter: false`. Turn that off when something else, such as a queue
@@ -304,9 +308,11 @@ const { data } = await testApi.get("https://api.example.com/feed"); // { ok: tru
 await faxios.get("https://api.example.com/feed", { fetchOptions: { cache: "no-store" } });
 ```
 
-- `fetchOptions` is spread into the init object passed to `fetch`. faxios sets `signal`, `method`,
-  `headers`, `body`, `duplex` and `credentials` itself, and those override the same keys in
-  `fetchOptions`.
+- Every own enumerable key of `fetchOptions` is copied into a null-prototype init passed to
+  `fetch`, including runtime extensions (Next.js `next`, Workers `cf`, undici `dispatcher`).
+  Inherited keys are ignored. faxios sets `signal`, `method`, `headers`, `body`, `duplex` and
+  `credentials` itself and ignores those keys in `fetchOptions`.
+- `env.fetch`, `env.Request` and `env.Response` count only as own properties of `env`.
 - Plain-object values inside `fetchOptions` are copied when configs merge; class instances are
   passed by reference.
 - Proxies are runtime configuration, not a faxios option. In Node, the project docs route a
@@ -353,9 +359,9 @@ export only. Instances from `create()` do not have them; import them by name ins
    `faxios.plugins` is undefined. Import from `@gcmdev/faxios/plugins/<name>`.
 7. **MEDIUM: Calling statics on an instance.** `api.isCancel(e)` is undefined on a `create()`
    instance. Use the named import.
-8. **MEDIUM: Expecting `onUploadProgress` everywhere.** It fires only where `fetch` can stream a
-   request body (`duplex: "half"`, for example Node). Browsers generally do not report upload
-   progress through fetch; do not promise it there.
+8. **MEDIUM: Expecting `onUploadProgress` everywhere.** It fires only where faxios can stream
+   the request body (Node; not Deno or Bun). In browsers and web workers faxios never streams the
+   body for progress, so the callback is not called; do not promise it there. Source: `src/lib/adapters/fetch.ts` (`isBrowserRuntime`).
 9. **MEDIUM: Retrying POST by accident or by assumption.** The retry plugin skips POST and PATCH
    unless they are listed in `methods`; a custom `retryOn` cannot override that.
 10. **MEDIUM: Downloading a binary body without `responseType`.** The bytes are decoded as UTF-8

package/skills/configure-requests/references/axios-differences.md

@@ -23,7 +23,7 @@ behaviour outside this list as unverified until the installed types and a test p
 | `proxy: {...}` / `httpAgent` / `httpsAgent` | Runtime-level proxy config. In Node the project docs pass an `undici` `ProxyAgent` as `fetchOptions.dispatcher`, using the app's own `undici` dependency | Not faxios options; faxios passes the dispatcher to `fetch` but does not test proxying |
 | `maxRedirects`, `beforeRedirect` | fetch follows redirects; `fetchOptions: { redirect: "manual" }` to stop | `ERR_FR_TOO_MANY_REDIRECTS` is never raised |
 | `maxRate`, `socketPath`, `decompress`, `insecureHTTPParser`, `httpVersion`, HTTP/2 options, `lookup`, `family` | none | Removed; ignored at runtime when untyped |
-| `onUploadProgress` | same option | Fires only where fetch streams request bodies (Node); not a browser guarantee |
+| `onUploadProgress` | same option | Fires only where fetch streams request bodies (Node); never called in browsers or web workers |
 | `responseType: "document"` | none in practice | Falls back to text |
 | retry via `axios-retry` | `retry()` from `@gcmdev/faxios/plugins/retry` | POST/PATCH excluded by default |
 | auth header interceptor | `authBearer()` from `@gcmdev/faxios/plugins/auth-bearer` | Sends only to the baseURL origin by default |

package/skills/configure-requests/references/plugins.md

@@ -85,21 +85,49 @@ Check: `faxios.get("/orders", { trace: "x" })` on an instance without the plugin
 installing it before `authBearer`:
 
 ```ts
-import faxios, { FaxiosError, type FaxiosContext } from "@gcmdev/faxios";
+import faxios, { type FaxiosContext } from "@gcmdev/faxios";
 import { definePlugin } from "@gcmdev/faxios/plugins";
 import { authBearer, type AuthBearerCapability } from "@gcmdev/faxios/plugins/auth-bearer";
 
+function requireSignIn() {
+  return definePlugin({
+    name: "requireSignIn",
+    middleware: async (ctx: FaxiosContext<unknown, AuthBearerCapability>, next) => {
+      if (!(await ctx.capabilities.auth.getToken())) throw new Error("Sign in first");
+      return next(ctx);
+    },
+  });
+}
+
+const api = faxios
+  .create({ baseURL: "https://api.example.com" })
+  .use(authBearer(() => "token"))
+  .use(requireSignIn());
+```
+
+## Refresh a token after a 401
+
+Install the refresh plugin before `authBearer` and never set `Authorization` in it. The retry
+runs `authBearer` again, which calls `getToken` and applies its origin rule, so a third-party 401
+is retried without the token. Share one in-flight refresh so rotating refresh tokens aren't spent twice:
+
+```ts
+import faxios, { FaxiosError } from "@gcmdev/faxios";
+import { definePlugin } from "@gcmdev/faxios/plugins";
+import { authBearer } from "@gcmdev/faxios/plugins/auth-bearer";
+
 function refreshOn401(refresh: () => Promise<void>) {
+  let refreshing: Promise<void> | undefined;
   return definePlugin({
     name: "refreshOn401",
-    middleware: async (ctx: FaxiosContext<unknown, AuthBearerCapability>, next) => {
+    middleware: async (ctx, next) => {
       try {
         return await next(ctx);
       }
       catch (error) {
         if (!(error instanceof FaxiosError) || error.response?.status !== 401) throw error;
-        await refresh();
-        ctx.config.headers.set("Authorization", `Bearer ${await ctx.capabilities.auth.getToken()}`);
+        refreshing ??= refresh().finally(() => { refreshing = undefined; });
+        await refreshing;
         return next(ctx);
       }
     },
@@ -109,10 +137,13 @@ function refreshOn401(refresh: () => Promise<void>) {
 let token = "old";
 const api = faxios
   .create({ baseURL: "https://api.example.com" })
-  .use(authBearer(() => token))
-  .use(refreshOn401(async () => { token = "new"; }));
+  .use(refreshOn401(async () => { token = "new"; }))
+  .use(authBearer(() => token));
 ```
 
+Calling `next` again re-sends the body. A stream body is used up by the first try; sending it
+again rejects with `ERR_BAD_REQUEST`.
+
 ## Rules `.use()` enforces at runtime
 
 - `name` must be a non-empty own string, otherwise `ERR_BAD_OPTION_VALUE`.

package/src/index.ts

@@ -11,7 +11,7 @@ import type { CreateFaxiosDefaults } from "./lib/types.ts";
 export { default as Faxios } from "./lib/core/Faxios.ts";
 export { default as FaxiosError, isSchemaValidationError } from "./lib/core/FaxiosError.ts";
 export type { SchemaValidationError } from "./lib/core/FaxiosError.ts";
-export { default as CanceledError, default as Cancel } from "./lib/cancel/CanceledError.ts";
+export { default as Cancel, default as CanceledError } from "./lib/cancel/CanceledError.ts";
 export { default as isCancel } from "./lib/cancel/isCancel.ts";
 export { default as isFaxiosError } from "./lib/helpers/isFaxiosError.ts";
 export { default as toFormData } from "./lib/helpers/toFormData.ts";
@@ -23,28 +23,28 @@ export { VERSION } from "./lib/env/data.ts";
 export type { FaxiosInstance, FaxiosStatic } from "./lib/faxios.ts";
 export type { StandardSchemaV1 } from "./lib/types/standard-schema.ts";
 export type { BasePerCallConfig, DefineConfig, DefinedEndpoint, FaxiosLike, PerCallConfig } from "./lib/core/define.ts";
-export type { RouteConfig, RouteMethodConfig, RouteBuilder } from "./lib/core/route.ts";
+export type { RouteBuilder, RouteConfig, RouteMethodConfig } from "./lib/core/route.ts";
 
 export type {
+  CreateFaxiosDefaults,
+  FaxiosConfigHeaders,
+  FaxiosContext,
+  FaxiosHeaderValue,
+  FaxiosMiddleware,
+  FaxiosNext,
+  FaxiosPlugin,
+  FaxiosPromise,
   FaxiosRequestConfig,
-  InternalFaxiosRequestConfig,
-  FaxiosResponse,
   FaxiosRequestHeaders,
+  FaxiosResponse,
   FaxiosResponseHeadersLike,
-  FaxiosHeaderValue,
-  Method,
-  ResponseType,
   GenericHTMLFormElement,
+  HeadersDefaults,
+  InternalFaxiosRequestConfig,
+  Method,
   RawFaxiosRequestConfig,
-  FaxiosPromise,
-  CreateFaxiosDefaults,
-  FaxiosConfigHeaders,
   RawFaxiosRequestHeaders,
-  HeadersDefaults,
-  FaxiosContext,
-  FaxiosNext,
-  FaxiosMiddleware,
-  FaxiosPlugin
+  ResponseType
 } from "./lib/types.ts";
 
 // Instance-synthesized members (no 1:1 source module). Types are self-contained

package/src/lib/adapters/fetch-helpers.ts

@@ -3,9 +3,9 @@
 import FaxiosError from "../core/FaxiosError.js";
 import type FaxiosHeaders from "../core/FaxiosHeaders.js";
 import type {
-  InternalFaxiosRequestConfig,
   FaxiosRequestHeaders,
-  FaxiosResponse
+  FaxiosResponse,
+  InternalFaxiosRequestConfig
 } from "../types.js";
 import utils from "../utils.js";
 
@@ -144,7 +144,7 @@ export const cleanFormDataContentType = (
   headers: FaxiosRequestHeaders
 ): void => {
   if (utils.isFormData(data)) {
-    const contentType = headers.getContentType() as string | null | undefined;
+    const contentType = headers.getContentType() as null | string | undefined;
     if (
       contentType &&
       /^multipart\/form-data/i.test(contentType) &&