@gcmdev/faxios 0.2.0 → 0.2.2

package/skills/configure-requests/SKILL.md

@@ -13,7 +13,7 @@ metadata:
     generating Axios APIs that faxios removed or never verified.
   type: core
   library: '@gcmdev/faxios'
-  library_version: '0.2.0'
+  library_version: '0.2.1'
 sources:
   - src/index.ts
   - src/lib/faxios.ts
@@ -22,6 +22,8 @@ sources:
   - src/lib/core/buildFullPath.ts
   - src/lib/core/dispatchRequest.ts
   - src/lib/core/FaxiosError.ts
+  - src/lib/core/define.ts
+  - src/lib/core/route.ts
   - src/lib/types.ts
   - src/lib/adapters/fetch.ts
   - src/lib/helpers/composeSignals.ts
@@ -70,7 +72,7 @@ const { data, status } = await api.get<{ id: number; name: string }>("/users/1")
 - `get`, `delete`, `head`, `options` take `(url, config?)`.
 - `post`, `put`, `patch`, `query` take `(url, data?, config?)`. `query` sends the HTTP QUERY method.
 - `postForm`, `putForm`, `patchForm` send `multipart/form-data`.
-- `api.getUri(config)` returns the URL faxios would request, without sending anything.
+- `api.getUri(config)` builds the URL from `baseURL`, `url` and `params` without sending anything. It doesn't substitute `pathParams`, so `{key}` placeholders stay as written.
 
 Path and query parameters:
 
@@ -84,8 +86,23 @@ 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`:
+
+```ts
+import faxios from "@gcmdev/faxios";
+
+const { data } = await faxios.get<ArrayBuffer>("https://example.com/report.zip", {
+  responseType: "arraybuffer",
+  maxContentLength: 50 * 1024 * 1024, // the body is buffered; cap it for untrusted servers
+});
+console.log(data.byteLength);
+```
+
+Unset `responseType` reads the body as text, then JSON-parses it if it parses. `"text"` skips the
+JSON parse; `"blob"`, `"formdata"` and `"stream"` (a `ReadableStream`) are also supported.
 
 ### Merge defaults the way faxios does
 
@@ -134,7 +151,29 @@ catch (error) {
   `ERR_BAD_RESPONSE_SCHEMA`, `error.response.data` is the body the schema rejected. Schemas run
   inside dispatch, so middleware sees the unvalidated config before `next(ctx)`.
 - For reusable typed endpoints, use `api.define(method, url, config)` or `api.route(url, config)`
-  rather than wrapping calls by hand.
+  rather than wrapping calls by hand. They return plain functions with no `.use()`
+  (`api.define(...).use(...)` is a TypeError), so put middleware on the instance and call
+  `define()`/`route()` on the value `.use()` returned. Middleware added later still runs (the
+  endpoint calls `api.request()` each time), but only that value types plugin options.
+  `pathParams` is accepted only when `pathParamsSchema` is set.
+
+```ts
+import faxios from "@gcmdev/faxios";
+import { z } from "zod";
+
+const api = faxios
+  .create({ baseURL: "https://api.example.com" })
+  .use(async (ctx, next) => next(ctx));
+const getUser = api.define("get", "/users/{id}", {
+  pathParamsSchema: z.object({ id: z.string() }),
+  responseSchema: z.object({ name: z.string() }),
+});
+const { data } = await getUser({ pathParams: { id: "123" } });
+console.log(data.name);
+```
+
+- With a plugin such as `retry()`, see "Define endpoints on a plugin instance" in
+  [references/plugins.md](references/plugins.md).
 
 ### Cancel requests and apply timeouts
 
@@ -234,6 +273,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
@@ -265,9 +305,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
@@ -319,6 +361,9 @@ export only. Instances from `create()` do not have them; import them by name ins
    progress through fetch; do not promise it there.
 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
+    text and come back corrupted. Set `responseType: "arraybuffer"` and type the call with
+    `get<ArrayBuffer>`. Source: `src/lib/adapters/fetch.ts`.
 
 ## Completion
 

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

@@ -27,6 +27,23 @@ Check: `faxios.get("/health", { retry: false })` on the default export (or any i
 `retry()` installed) is a type error. Use the value `.use()` returned. The option defaults and
 ordering rules are in the SKILL.md "Use the built-in plugins from their subpaths" section.
 
+## Define endpoints on a plugin instance
+
+`define()` and `route()` return plain functions with no `.use()`. Install plugins first and call
+`define()` on the value `.use()` returned, so the endpoint's per-call config types `retry`:
+
+```ts
+import faxios from "@gcmdev/faxios";
+import { retry } from "@gcmdev/faxios/plugins/retry";
+import { z } from "zod";
+
+const api = faxios.create({ baseURL: "https://tags.tiqcdn.com" }).use(retry());
+const getDistro = api.define("get", "/utag/{account}/{profile}/prod/distro.zip", {
+  pathParamsSchema: z.object({ account: z.string(), profile: z.string() }),
+});
+await getDistro({ pathParams: { account: "acme", profile: "main" }, retry: { attempts: 2 } });
+```
+
 ## Build a plugin with `definePlugin`
 
 `definePlugin` comes from `@gcmdev/faxios/plugins`. It returns the same object and only changes the
@@ -68,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);
       }
     },
@@ -92,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

@@ -0,0 +1,57 @@
+// @ts-self-types="./index.d.ts"
+/* eslint-disable no-barrel-files/no-barrel-files */
+import faxios from "./lib/faxios.ts";
+import type { FaxiosInstance, FaxiosStatic } from "./lib/faxios.ts";
+import type { CreateFaxiosDefaults } from "./lib/types.ts";
+
+// Static re-exports so the emitted .d.ts references source modules.
+// zshy rewrites .ts -> .js for static import/export, but NOT for inline
+// import() type expressions (ImportTypeNode). Destructuring these off the
+// runtime instance forced TS to emit the broken inline `import("./x.ts")` form.
+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 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";
+export { default as FaxiosHeaders } from "./lib/core/FaxiosHeaders.ts";
+export { default as HttpStatusCode } from "./lib/helpers/HttpStatusCode.ts";
+export { default as mergeConfig } from "./lib/core/mergeConfig.ts";
+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 { RouteBuilder, RouteConfig, RouteMethodConfig } from "./lib/core/route.ts";
+
+export type {
+  CreateFaxiosDefaults,
+  FaxiosConfigHeaders,
+  FaxiosContext,
+  FaxiosHeaderValue,
+  FaxiosMiddleware,
+  FaxiosNext,
+  FaxiosPlugin,
+  FaxiosPromise,
+  FaxiosRequestConfig,
+  FaxiosRequestHeaders,
+  FaxiosResponse,
+  FaxiosResponseHeadersLike,
+  GenericHTMLFormElement,
+  HeadersDefaults,
+  InternalFaxiosRequestConfig,
+  Method,
+  RawFaxiosRequestConfig,
+  RawFaxiosRequestHeaders,
+  ResponseType
+} from "./lib/types.ts";
+
+// Instance-synthesized members (no 1:1 source module). Types are self-contained
+// (all/formToJSON) or annotated with statically imported types (create), so no
+// inline import() is emitted. Runtime values are the same references as on the instance.
+export const all: FaxiosStatic["all"] = faxios.all;
+export const formToJSON: FaxiosStatic["formToJSON"] = faxios.formToJSON;
+export const create: (instanceConfig?: CreateFaxiosDefaults) => FaxiosInstance = faxios.create;
+
+export { faxios as default };

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

@@ -0,0 +1,167 @@
+"use strict";
+
+import FaxiosError from "../core/FaxiosError.js";
+import type FaxiosHeaders from "../core/FaxiosHeaders.js";
+import type {
+  FaxiosRequestHeaders,
+  FaxiosResponse,
+  InternalFaxiosRequestConfig
+} from "../types.js";
+import utils from "../utils.js";
+
+export type ComposedSignal = AbortSignal & { unsubscribe?: () => void; };
+export type PendingBodyErrorRef = { value: (FaxiosError & { request?: unknown; }) | null; };
+
+const _textEncoder: TextEncoder | undefined =
+  typeof globalThis.TextEncoder === "function" ? new globalThis.TextEncoder() : undefined;
+
+// ponytail: exported for unit testing only — not part of public API
+export const checkDeclaredContentLength = (
+  responseHeaders: FaxiosHeaders,
+  hasMaxContentLength: boolean,
+  maxContentLength: number,
+  config: InternalFaxiosRequestConfig,
+  request: unknown
+): void => {
+  if (!hasMaxContentLength) return;
+  const declaredLength = utils.toFiniteNumber(
+    (responseHeaders.getContentLength as () => unknown)()
+  );
+  if (declaredLength != null && declaredLength > maxContentLength) {
+    throw new FaxiosError(
+      "maxContentLength size of " + maxContentLength + " exceeded",
+      FaxiosError.ERR_BAD_RESPONSE,
+      config,
+      request
+    );
+  }
+};
+
+// ponytail: exported for unit testing only — not part of public API
+export const checkMaterializedSize = (
+  responseData: unknown,
+  hasMaxContentLength: boolean,
+  maxContentLength: number,
+  isStreamResponse: boolean,
+  supportsResponseStream: boolean,
+  config: InternalFaxiosRequestConfig,
+  request: unknown
+): void => {
+  if (!hasMaxContentLength || supportsResponseStream || isStreamResponse) return;
+  if (responseData == null) return;
+  let materializedSize: number | undefined;
+  const rd = responseData as Record<string, unknown>;
+  if (typeof rd["byteLength"] === "number") {
+    materializedSize = rd["byteLength"];
+  }
+  else if (typeof rd["size"] === "number") {
+    materializedSize = rd["size"];
+  }
+  else if (typeof responseData === "string") {
+    materializedSize = _textEncoder
+      ? _textEncoder.encode(responseData).byteLength
+      : responseData.length;
+  }
+  if (typeof materializedSize === "number" && materializedSize > maxContentLength) {
+    throw new FaxiosError(
+      "maxContentLength size of " + maxContentLength + " exceeded",
+      FaxiosError.ERR_BAD_RESPONSE,
+      config,
+      request
+    );
+  }
+};
+
+// ponytail: exported for unit testing only — not part of public API
+export const handleFetchCaughtError = (
+  err: unknown,
+  composedSignal: ComposedSignal | undefined,
+  pendingBodyErrorRef: PendingBodyErrorRef,
+  config: InternalFaxiosRequestConfig,
+  request: unknown
+): never => {
+  // Safari can surface fetch aborts as a DOMException-like object whose
+  // branded getters throw. Prefer our composed signal reason before reading
+  // the caught error, preserving timeout vs cancellation semantics.
+  if (
+    composedSignal &&
+    composedSignal.aborted &&
+    composedSignal.reason instanceof FaxiosError
+  ) {
+    const canceledError = composedSignal.reason;
+    canceledError.config = config;
+    request && (canceledError.request = request);
+    err !== canceledError && (canceledError.cause = err as Error);
+    throw canceledError;
+  }
+
+  // Surface a maxBodyLength violation we raised while the request body was
+  // being streamed. Matching by identity keeps the error deterministic across
+  // runtimes and avoids prototype-pollution reads.
+  if (pendingBodyErrorRef.value) {
+    const _pbe = pendingBodyErrorRef.value;
+    request && !_pbe.request && (_pbe.request = request);
+    throw _pbe;
+  }
+
+  // Re-throw FaxiosErrors we raised synchronously without re-wrapping them.
+  if (err instanceof FaxiosError) {
+    request && !err.request && (err.request = request);
+    throw err;
+  }
+
+  const _err = err as Record<string, unknown> & Error;
+  if (
+    _err.name === "TypeError" &&
+    /Load failed|fetch/i.test(_err.message)
+  ) {
+    throw Object.assign(
+      new FaxiosError(
+        "Network Error",
+        FaxiosError.ERR_NETWORK,
+        config,
+        request,
+        _err["response"] as FaxiosResponse | undefined
+      ),
+      {
+        cause: _err["cause"] || _err,
+      }
+    );
+  }
+
+  throw FaxiosError.from(
+    _err,
+    _err["code"] as string | undefined,
+    config,
+    request,
+    _err["response"] as FaxiosResponse | undefined
+  );
+};
+
+// ponytail: exported for unit testing only — not part of public API
+export const cleanFormDataContentType = (
+  data: unknown,
+  headers: FaxiosRequestHeaders
+): void => {
+  if (utils.isFormData(data)) {
+    const contentType = headers.getContentType() as null | string | undefined;
+    if (
+      contentType &&
+      /^multipart\/form-data/i.test(contentType) &&
+      !/boundary=/i.test(contentType)
+    ) {
+      headers.delete("content-type");
+    }
+  }
+};
+
+// ponytail: exported for unit testing only — not part of public API
+export const encodeBodyIfNeeded = (
+  data: unknown,
+  headers: Record<string, unknown>,
+  encode: (str: string) => Promise<Uint8Array> | Uint8Array
+): Promise<unknown> | unknown => {
+  if (!utils.isString(data) || utils.findKey(headers, "content-type")) return data;
+  // ponytail: skip await when TextEncoder is sync (avoids microtask hop on every string body)
+  return encode(data as string);
+};