@marianmeres/http-utils 2.5.0 → 2.6.0

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 ```yaml
 name: "@marianmeres/http-utils"
-version: "2.0.2"
+version: "2.5.1"
 license: MIT
 runtime: deno, node
 type: library
@@ -46,19 +46,40 @@ function createHttpApi(
 | `put` | `put(path, options?: DataOptions): Promise<unknown>` | PUT request |
 | `patch` | `patch(path, options?: DataOptions): Promise<unknown>` | PATCH request |
 | `del` | `del(path, options?: DataOptions): Promise<unknown>` | DELETE request |
-| `url` | `url(path: string): string` | Build full URL |
+| `url` | `url(path: string): string` | Build full URL (base trailing slash + path leading slash normalized) |
 | `base` | `get/set base: string \| null` | Base URL property |
+| `onRequest` | `onRequest(i: RequestInterceptor \| null): this` | Register request interceptor |
+| `onResponse` | `onResponse(i: ResponseInterceptor \| null): this` | Register response interceptor |
 
 ### Exported Types
 
 ```typescript
-type RequestData = Record<string, unknown> | FormData | string | null;
+type RequestData =
+  | Record<string, unknown>
+  | unknown[]
+  | FormData
+  | Blob
+  | ArrayBuffer
+  | ArrayBufferView
+  | URLSearchParams
+  | ReadableStream
+  | string
+  | number
+  | boolean
+  | null;
+
+type QueryValue =
+  | string | number | boolean
+  | (string | number | boolean)[]
+  | null | undefined;
 
 interface FetchParams {
   data?: RequestData;
   token?: string | null;
-  headers?: Record<string, string> | null;
+  headers?: HeadersInit | null;
   signal?: AbortSignal;
+  timeout?: number | null;               // ms
+  query?: Record<string, QueryValue> | null;
   credentials?: 'omit' | 'same-origin' | 'include' | null;
   raw?: boolean | null;
   assert?: boolean | null;
@@ -79,6 +100,16 @@ interface DataOptions {
 
 type ErrorMessageExtractor = (body: unknown, response: Response) => string;
 type ResponseHeaders = Record<string, string | number>;
+
+type RequestInterceptor = (
+  init: RequestInit,
+  ctx: { method: string; url: string }
+) => RequestInit | void | Promise<RequestInit | void>;
+
+type ResponseInterceptor = (
+  response: Response,
+  ctx: { method: string; url: string }
+) => Response | void | Promise<Response | void>;
 ```
 
 ### Error Classes (HTTP_ERROR namespace)
@@ -138,12 +169,26 @@ class HTTP_STATUS {
 
 ## Key Behaviors
 
-1. **Auto JSON parsing**: Response bodies are automatically parsed as JSON if possible
+1. **Auto JSON parsing**: Response bodies are parsed as JSON if possible; empty bodies (204/205) return `null`
 2. **Bearer token**: `token` param auto-adds `Authorization: Bearer {token}` header
 3. **Error throwing**: By default, non-OK responses throw HttpError (disable with `assert: false`)
 4. **Response headers**: Pass `respHeaders: {}` to capture response headers (mutated in place)
-5. **Raw response**: Use `raw: true` to get raw Response object instead of parsed body
-6. **Error priority**: per-request extractor → per-instance → global → built-in fallback
+5. **Raw response**: Use `raw: true` to get raw Response object; the caller must consume the body
+6. **Error priority**: per-request extractor → per-instance → global → built-in fallback; a throwing extractor falls through to the next priority rather than crashing
+7. **URL normalization**: `#url(path)` strips trailing `/` from base and ensures leading `/` on path, so `base + path` never produces `//` or missing `/`
+8. **Timeout**: `params.timeout` (ms) aborts via `AbortSignal.timeout`; composed with `params.signal` via `AbortSignal.any`
+9. **Query**: `params.query` object appended as URL search params; `null`/`undefined` skipped, arrays → repeated keys
+
+## Request Body Serialization
+
+| Runtime type | Sent as | Content-Type set |
+|---|---|---|
+| `null` / `undefined` | No body | — |
+| `string` | raw | caller-controlled |
+| `number` / `boolean` / plain object / array | `JSON.stringify` | `application/json` only if not already set |
+| `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, typed arrays, `ReadableStream` | passed to fetch unchanged | fetch handles (e.g. multipart boundary, form-urlencoded) |
+
+User-provided `Content-Type` header is always preserved.
 
 ## Development Commands
 

package/API.md

@@ -7,6 +7,10 @@ Complete API reference for `@marianmeres/http-utils`.
 - [createHttpApi](#createhttpapi)
 - [opts](#opts)
 - [HttpApi Class](#httpapi-class)
+- [Request Bodies](#request-bodies)
+- [Query Parameters](#query-parameters)
+- [Timeouts and Cancellation](#timeouts-and-cancellation)
+- [Interceptors](#interceptors)
 - [Types](#types)
 - [HTTP Errors](#http-errors)
 - [HTTP Status Codes](#http-status-codes)
@@ -208,7 +212,7 @@ Performs a DELETE request. Same signature as `post<T>()`.
 
 #### `url(path)`
 
-Builds the full URL from a path.
+Builds the full URL from a path. Base trailing slashes and missing path leading slashes are normalized so there is exactly one `/` between base and path.
 
 ```ts
 url(path: string): string
@@ -217,10 +221,22 @@ url(path: string): string
 **Example:**
 ```ts
 const api = createHttpApi("https://api.example.com");
-api.url("/users"); // "https://api.example.com/users"
-api.url("https://other.com/path"); // "https://other.com/path" (absolute URLs returned as-is)
+api.url("/users");                  // "https://api.example.com/users"
+api.url("users");                   // "https://api.example.com/users" (leading slash added)
+api.url("https://other.com/path");  // "https://other.com/path" (absolute URLs returned as-is)
+
+const api2 = createHttpApi("https://api.example.com/v1/");
+api2.url("/users");                 // "https://api.example.com/v1/users" (no double slash)
 ```
 
+#### `onRequest(interceptor)`
+
+Registers a request interceptor. See [Interceptors](#interceptors).
+
+#### `onResponse(interceptor)`
+
+Registers a response interceptor. See [Interceptors](#interceptors).
+
 ### Properties
 
 #### `base`
@@ -234,14 +250,160 @@ set base(v: string | null | undefined)
 
 ---
 
+## Request Bodies
+
+The `data` parameter is serialized based on its runtime type:
+
+| Runtime type | Behavior | Content-Type |
+|---|---|---|
+| `null` / `undefined` | No body sent | — |
+| `string` | Sent as-is | Caller's (fetch may default to `text/plain;charset=UTF-8`) |
+| `number` / `boolean` | `JSON.stringify`'d (e.g. `0` → `"0"`) | `application/json` if not set |
+| Plain object / array | `JSON.stringify`'d | `application/json` if not set |
+| `FormData` | Passed to fetch unchanged | `multipart/form-data; boundary=…` (fetch auto-sets) |
+| `URLSearchParams` | Passed to fetch unchanged | `application/x-www-form-urlencoded;charset=UTF-8` (fetch auto-sets) |
+| `Blob` | Passed to fetch unchanged | From the Blob's `.type` |
+| `ArrayBuffer` / typed arrays | Passed to fetch unchanged | Caller's (none by default) |
+| `ReadableStream` | Passed to fetch unchanged | Caller's |
+
+If you explicitly set `Content-Type` in `headers`, it is always respected — even for object data. Objects are still JSON-stringified; set your own body (e.g. via a string) if you need a non-JSON serialization.
+
+```ts
+// Plain object → JSON
+await api.post("/users", { name: "John" });
+
+// Respect user Content-Type
+await api.post("/graph", { query: "{ me { id } }" }, {
+  headers: { "content-type": "application/graphql+json" },
+});
+
+// FormData (file upload)
+const fd = new FormData();
+fd.append("file", fileBlob);
+await api.post("/upload", fd);
+
+// URL-encoded form
+await api.post("/login", new URLSearchParams({ user: "a", pass: "b" }));
+
+// Raw string body
+await api.post("/logs", "raw log line", {
+  headers: { "content-type": "text/plain" },
+});
+```
+
+---
+
+## Query Parameters
+
+Use `params.query` to append query-string parameters to the URL.
+
+```ts
+await api.get("/search", {
+  query: {
+    q: "hello world",
+    page: 1,
+    active: true,
+    tag: ["a", "b"],      // → ?tag=a&tag=b
+    ignored: null,         // null and undefined are skipped
+  },
+});
+// GET /search?q=hello+world&page=1&active=true&tag=a&tag=b
+```
+
+If the path already contains `?`, query params are appended with `&`.
+
+---
+
+## Timeouts and Cancellation
+
+`params.timeout` (in milliseconds) aborts the request via `AbortSignal.timeout`. It composes with a user-provided `signal` — whichever fires first aborts the request.
+
+```ts
+// Simple timeout
+await api.get("/slow", { timeout: 5000 });
+
+// Timeout + cancellable signal
+const ctrl = new AbortController();
+await api.get("/slow", {
+  timeout: 10_000,
+  signal: ctrl.signal,
+});
+// ctrl.abort() or timeout — whichever first — cancels the request.
+```
+
+Uses `AbortSignal.any` when available (Node 20+, modern Deno). Falls back to manual composition otherwise.
+
+---
+
+## Interceptors
+
+Register per-instance hooks that run around each request.
+
+### `onRequest(interceptor)`
+
+Called after defaults are merged, with the final `RequestInit` and resolved URL. Return a new `RequestInit` to replace the original, or `void` / `undefined` to keep it.
+
+```ts
+const api = createHttpApi("https://api.example.com").onRequest((init, ctx) => {
+  console.log(`[http] → ${ctx.method} ${ctx.url}`);
+  const h = new Headers(init.headers);
+  h.set("x-trace-id", crypto.randomUUID());
+  return { ...init, headers: h };
+});
+```
+
+### `onResponse(interceptor)`
+
+Called before the body is consumed. **Must not read the body.** Return a replacement `Response` (e.g. after a retry) or `void` to keep the original. If you return a replacement, the original's body is cancelled for you.
+
+```ts
+api.onResponse(async (resp, ctx) => {
+  console.log(`[http] ← ${ctx.method} ${ctx.url} ${resp.status}`);
+  if (resp.status === 401) {
+    await refreshToken();
+    // return a new fetch() if you want to retry
+  }
+});
+```
+
+Only one interceptor of each kind is supported per instance. Passing `null` clears it.
+
+---
+
 ## Types
 
 ### RequestData
 
-Request body data type.
+Request body data type. See [Request Bodies](#request-bodies) for serialization rules.
+
+```ts
+type RequestData =
+  | Record<string, unknown>
+  | unknown[]
+  | FormData
+  | Blob
+  | ArrayBuffer
+  | ArrayBufferView
+  | URLSearchParams
+  | ReadableStream
+  | string
+  | number
+  | boolean
+  | null;
+```
+
+### QueryValue
+
+A value for `FetchParams.query`. `null` / `undefined` entries are skipped; arrays emit repeated keys.
 
 ```ts
-type RequestData = Record<string, unknown> | FormData | string | null;
+type QueryValue =
+  | string
+  | number
+  | boolean
+  | (string | number | boolean)[]
+  | null
+  | undefined;
 ```
 
 ### FetchParams
@@ -250,17 +412,21 @@ Parameters for fetch requests.
 
 ```ts
 interface FetchParams {
-  /** Request body data (automatically JSON stringified unless FormData). */
+  /** Request body. See "Request Bodies" for serialization rules. */
   data?: RequestData;
   /** Bearer token (auto-adds `Authorization: Bearer {token}` header). */
   token?: string | null;
   /** Custom request headers. */
-  headers?: Record<string, string> | null;
-  /** AbortSignal for request cancellation. */
+  headers?: HeadersInit | null;
+  /** AbortSignal for request cancellation. Combined with `timeout` if both are set. */
   signal?: AbortSignal;
+  /** Abort the request after this many milliseconds. Combined with `signal`. */
+  timeout?: number | null;
+  /** Query parameters appended to the URL. */
+  query?: Record<string, QueryValue> | null;
   /** Credentials mode for the request. */
   credentials?: 'omit' | 'same-origin' | 'include' | null;
-  /** If true, returns the raw Response object instead of parsed body. */
+  /** If true, returns the raw Response object instead of parsed body. Caller must consume the body. */
   raw?: boolean | null;
   /** If false, does not throw on HTTP errors (default: true). */
   assert?: boolean | null;
@@ -313,12 +479,30 @@ Special keys added after request:
 
 ### ErrorMessageExtractor
 
-Function to extract error messages from failed HTTP responses.
+Function to extract error messages from failed HTTP responses. If the extractor throws, the call falls back to the next-priority extractor (per-instance → global → built-in) instead of crashing.
 
 ```ts
 type ErrorMessageExtractor = (body: unknown, response: Response) => string;
 ```
 
+### RequestInterceptor
+
+```ts
+type RequestInterceptor = (
+  init: RequestInit,
+  context: { method: string; url: string }
+) => RequestInit | void | Promise<RequestInit | void>;
+```
+
+### ResponseInterceptor
+
+```ts
+type ResponseInterceptor = (
+  response: Response,
+  context: { method: string; url: string }
+) => Response | void | Promise<Response | void>;
+```
+
 ---
 
 ## HTTP Errors

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/README.md

@@ -137,14 +137,35 @@ try {
 
 ### Key Features
 
-- **Auto JSON**: Response bodies are automatically parsed as JSON
+- **Auto JSON**: Response bodies are automatically parsed as JSON; empty bodies (204/205) return `null`
+- **Smart body handling**: Plain objects → JSON; `FormData` / `URLSearchParams` / `Blob` / typed arrays / `ReadableStream` pass through; strings sent as-is
+- **Query params**: Pass `query: { page: 1, tag: ["a", "b"] }` for URL search params
+- **Timeouts**: Pass `timeout: 5000` for automatic request cancellation
 - **Bearer tokens**: Use `token` param to auto-add `Authorization: Bearer` header
 - **Response headers**: Pass `respHeaders: {}` to capture response headers
-- **Raw response**: Use `raw: true` to get the raw Response object
+- **Raw response**: Use `raw: true` to get the raw Response object (caller must consume the body)
 - **Non-throwing**: Use `assert: false` to prevent throwing on errors
-- **AbortController**: Pass `signal` for request cancellation
+- **AbortController**: Pass `signal` for request cancellation (composes with `timeout`)
+- **Interceptors**: `api.onRequest(...)` / `api.onResponse(...)` for tracing, auth refresh, etc.
 - **Typed responses**: Use generics for type-safe responses: `api.get<User>("/users/1")`
 
+### Query, Timeout, Interceptors
+
+```ts
+// Query params
+await api.get("/search", { query: { q: "hi", tag: ["a", "b"] } });
+
+// Timeout (abort after 5s; composes with AbortSignal)
+await api.get("/slow", { timeout: 5000 });
+
+// Interceptors
+api.onRequest((init, { method, url }) => {
+  console.log(method, url);
+}).onResponse(async (resp) => {
+  if (resp.status === 401) await refreshToken();
+});
+```
+
 ## Full API Reference
 
 For complete API documentation including all error classes, HTTP status codes, types, and utilities, see **[API.md](API.md)**.

package/dist/api.d.ts

@@ -6,28 +6,60 @@
  */
 /**
  * Request body data type.
- * Supports JSON-serializable objects, FormData for file uploads, or raw strings.
+ *
+ * Plain objects and arrays are JSON-serialized (with `Content-Type: application/json`
+ * when not set). Strings are sent as-is (the caller controls `Content-Type`).
+ * Native `BodyInit` types (`FormData`, `Blob`, `ArrayBuffer`, typed arrays,
+ * `URLSearchParams`, `ReadableStream`) are passed through unchanged so that
+ * `fetch` can handle content-type negotiation (e.g. multipart boundary for
+ * FormData, `application/x-www-form-urlencoded` for URLSearchParams).
  */
-export type RequestData = Record<string, unknown> | FormData | string | null;
+export type RequestData = Record<string, unknown> | unknown[] | FormData | Blob | ArrayBuffer | ArrayBufferView | URLSearchParams | ReadableStream | string | number | boolean | null;
+/** A primitive that can be serialized into a query-string value. */
+type QueryPrimitive = string | number | boolean;
+/** A value for {@link FetchParams.query}. `null`/`undefined` entries are skipped. */
+export type QueryValue = QueryPrimitive | QueryPrimitive[] | null | undefined;
 interface BaseParams {
     method: "GET" | "POST" | "PATCH" | "DELETE" | "PUT";
     path: string;
 }
+/**
+ * Request interceptor. Called after defaults are merged, with the final
+ * `RequestInit` and the resolved URL. May return an updated `RequestInit`
+ * (or a promise of one). Returning `undefined` keeps the original `init`.
+ */
+export type RequestInterceptor = (init: RequestInit, context: {
+    method: string;
+    url: string;
+}) => RequestInit | void | Promise<RequestInit | void>;
+/**
+ * Response interceptor. Called before the response body is consumed.
+ * May return a replacement `Response` (e.g. retry result); returning
+ * `undefined` keeps the original. Must not consume the response body.
+ */
+export type ResponseInterceptor = (response: Response, context: {
+    method: string;
+    url: string;
+}) => Response | void | Promise<Response | void>;
 /**
  * Parameters for fetch requests.
  */
 export interface FetchParams {
-    /** Request body data (automatically JSON stringified unless FormData). */
+    /** Request body. Plain objects/arrays are JSON-serialized; strings and native BodyInit types are passed through. */
     data?: RequestData;
     /** Bearer token (auto-adds `Authorization: Bearer {token}` header). */
     token?: string | null;
     /** Custom request headers. */
-    headers?: HeadersInit | Record<string, string> | null;
-    /** AbortSignal for request cancellation. */
+    headers?: HeadersInit | null;
+    /** AbortSignal for request cancellation. Combined with `timeout` if both are set. */
     signal?: AbortSignal;
+    /** Abort the request after this many milliseconds. Combined with `signal`. */
+    timeout?: number | null;
+    /** Query parameters appended to the URL. Null/undefined values skipped; arrays become repeated keys. */
+    query?: Record<string, QueryValue> | null;
     /** Credentials mode for the request. */
     credentials?: "omit" | "same-origin" | "include" | null;
-    /** If true, returns the raw Response object instead of parsed body. */
+    /** If true, returns the raw Response object instead of parsed body. Caller must consume the body. */
     raw?: boolean | null;
     /** If false, does not throw on HTTP errors (default: true). */
     assert?: boolean | null;
@@ -51,7 +83,7 @@ export type ResponseHeaders = Record<string, string | number>;
  * Options for HTTP GET requests using the new cleaner API.
  */
 export interface GetOptions {
-    /** Fetch parameters (headers, token, signal, credentials, raw, assert). */
+    /** Fetch parameters (headers, token, signal, credentials, raw, assert, timeout, query). */
     params?: FetchParams;
     /** Object to receive response headers (will be mutated). */
     respHeaders?: ResponseHeaders | null;
@@ -64,7 +96,7 @@ export interface GetOptions {
 export interface DataOptions {
     /** Request body data. */
     data?: RequestData;
-    /** Fetch parameters (headers, token, signal, credentials, raw, assert). */
+    /** Fetch parameters (headers, token, signal, credentials, raw, assert, timeout, query). */
     params?: FetchParams;
     /** Object to receive response headers (will be mutated). */
     respHeaders?: ResponseHeaders | null;
@@ -91,6 +123,16 @@ export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
 export declare class HttpApi {
     #private;
     constructor(base?: string | null, defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>), factoryErrorMessageExtractor?: ErrorMessageExtractor | null | undefined);
+    /**
+     * Register a request interceptor. Called after defaults are merged.
+     * Returning a new `RequestInit` replaces the original.
+     */
+    onRequest(interceptor: RequestInterceptor | null): this;
+    /**
+     * Register a response interceptor. Called before the body is consumed.
+     * Must not consume the body. Returning a new `Response` replaces the original.
+     */
+    onResponse(interceptor: ResponseInterceptor | null): this;
     /**
      * Performs a GET request (new options API - recommended).
      *
@@ -101,54 +143,23 @@ export declare class HttpApi {
      *
      * @example
      * ```ts
-     * const data = await api.get('/users', {
+     * const data = await api.get('/users', opts({
      *   params: { headers: { 'X-Custom': 'value' } },
      *   respHeaders: {}
-     * });
+     * }));
      * ```
      */
     get<T = unknown>(path: string, options: GetOptions): Promise<T>;
     /**
      * Performs a GET request (legacy API).
-     *
-     * @param path - The request path (will be appended to base URL if set).
-     * @param params - Optional fetch parameters.
-     * @param respHeaders - Optional object to be mutated with response headers.
-     * @param errorMessageExtractor - Optional custom error message extractor.
-     * @param _dumpParams - Internal parameter for testing.
-     * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
-     * @throws {HttpError} When the response is not OK and `assert` is true (default).
      */
     get<T = unknown>(path: string, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /**
      * Performs a POST request (new options API - recommended).
-     *
-     * @param path - The request path (will be appended to base URL if set).
-     * @param options - Request options object including data and params.
-     * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
-     * @throws {HttpError} When the response is not OK and `assert` is true (default).
-     *
-     * @example
-     * ```ts
-     * await api.post('/users', {
-     *   data: { name: 'John' },
-     *   params: { headers: { 'X-Custom': 'value' } },
-     *   respHeaders: {}
-     * });
-     * ```
      */
     post<T = unknown>(path: string, options: DataOptions): Promise<T>;
     /**
      * Performs a POST request (legacy API).
-     *
-     * @param path - The request path (will be appended to base URL if set).
-     * @param data - Request body data.
-     * @param params - Optional fetch parameters.
-     * @param respHeaders - Optional object to be mutated with response headers.
-     * @param errorMessageExtractor - Optional custom error message extractor.
-     * @param _dumpParams - Internal parameter for testing.
-     * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
-     * @throws {HttpError} When the response is not OK and `assert` is true (default).
      */
     post<T = unknown>(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<T>;
     /** Performs a PUT request (new options API). @see post */

package/dist/api.js

@@ -7,6 +7,7 @@
 import { createHttpError } from "./error.js";
 /**
  * Deep merges two objects. Later properties overwrite earlier properties.
+ * Arrays are overwritten, not concatenated (conventional behavior).
  */
 function deepMerge(target, source) {
     const output = { ...target };
@@ -32,6 +33,78 @@ function deepMerge(target, source) {
 function isObject(item) {
     return item !== null && typeof item === "object" && !Array.isArray(item);
 }
+/**
+ * Returns true for body types that native `fetch` knows how to serialize
+ * (including setting Content-Type where appropriate). These are passed through
+ * unchanged rather than JSON-stringified.
+ */
+function isNativeBodyInit(v) {
+    if (v instanceof FormData)
+        return true;
+    if (typeof Blob !== "undefined" && v instanceof Blob)
+        return true;
+    if (v instanceof ArrayBuffer)
+        return true;
+    if (ArrayBuffer.isView(v))
+        return true;
+    if (v instanceof URLSearchParams)
+        return true;
+    if (typeof ReadableStream !== "undefined" && v instanceof ReadableStream) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Appends query parameters to a URL path. Null/undefined values are skipped.
+ * Array values are emitted as repeated keys (e.g. `?tag=a&tag=b`).
+ */
+function appendQuery(path, query) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v === null || v === undefined)
+            continue;
+        if (Array.isArray(v)) {
+            for (const item of v) {
+                if (item !== null && item !== undefined)
+                    sp.append(k, String(item));
+            }
+        }
+        else {
+            sp.append(k, String(v));
+        }
+    }
+    const qs = sp.toString();
+    if (!qs)
+        return path;
+    return path + (path.includes("?") ? "&" : "?") + qs;
+}
+/**
+ * Combines a user-provided AbortSignal with an optional timeout-based signal.
+ * Returns `undefined` if neither is present.
+ */
+function composeSignal(userSignal, timeoutMs) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return userSignal;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (!userSignal)
+        return timeoutSignal;
+    // AbortSignal.any is available in Node 20+ and modern Deno.
+    if (typeof AbortSignal.any === "function") {
+        return AbortSignal.any([userSignal, timeoutSignal]);
+    }
+    // Fallback: manual composition.
+    const ctrl = new AbortController();
+    const abort = (reason) => ctrl.abort(reason);
+    if (userSignal.aborted)
+        abort(userSignal.reason);
+    else
+        userSignal.addEventListener("abort", () => abort(userSignal.reason));
+    if (timeoutSignal.aborted)
+        abort(timeoutSignal.reason);
+    else
+        timeoutSignal.addEventListener("abort", () => abort(timeoutSignal.reason));
+    return ctrl.signal;
+}
 /** Symbol marker for explicit options API detection. */
 const OPTIONS_MARKER = Symbol("options");
 /**
@@ -55,7 +128,6 @@ export function opts(options) {
  */
 function parseGetOptions(paramsOrOptions, legacyRespHeaders, legacyErrorExtractor) {
     if (paramsOrOptions && OPTIONS_MARKER in paramsOrOptions) {
-        // New options API (explicit via opts() wrapper)
         const o = paramsOrOptions;
         return {
             params: o.params,
@@ -63,7 +135,6 @@ function parseGetOptions(paramsOrOptions, legacyRespHeaders, legacyErrorExtracto
             errorExtractor: o.errorExtractor ?? null,
         };
     }
-    // Legacy positional API
     return {
         params: paramsOrOptions,
         respHeaders: legacyRespHeaders ?? null,
@@ -77,7 +148,6 @@ function parseDataOptions(dataOrOptions, legacyParams, legacyRespHeaders, legacy
     if (dataOrOptions &&
         typeof dataOrOptions === "object" &&
         OPTIONS_MARKER in dataOrOptions) {
-        // New options API (explicit via opts() wrapper)
         const o = dataOrOptions;
         return {
             data: o.data ?? null,
@@ -86,7 +156,6 @@ function parseDataOptions(dataOrOptions, legacyParams, legacyRespHeaders, legacy
             errorExtractor: o.errorExtractor ?? null,
         };
     }
-    // Legacy positional API
     return {
         data: dataOrOptions ?? null,
         params: legacyParams,
@@ -94,45 +163,79 @@ function parseDataOptions(dataOrOptions, legacyParams, legacyRespHeaders, legacy
         errorExtractor: legacyErrorExtractor ?? null,
     };
 }
-const _fetchRaw = async ({ method, path, data = null, token = null, headers = null, signal, credentials, }) => {
+/**
+ * Builds the final RequestInit and serialized URL from FetchParams.
+ * Does not call fetch.
+ */
+function buildRequest(params) {
+    const { method, path, data = null, token = null, headers = null, signal, timeout, query, credentials, } = params;
     const normalizedHeaders = {};
     if (headers) {
         new Headers(headers).forEach((value, key) => {
             normalizedHeaders[key] = value;
         });
     }
-    const opts = {
-        method,
-        credentials: credentials ?? undefined,
-        headers: normalizedHeaders,
-        signal,
-    };
-    if (data) {
-        const isObj = typeof data === "object";
-        // FormData: multipart/form-data -- no explicit Content-Type
-        if (data instanceof FormData) {
-            opts.body = data;
+    const init = { method };
+    if (credentials)
+        init.credentials = credentials;
+    const composedSignal = composeSignal(signal, timeout ?? undefined);
+    if (composedSignal)
+        init.signal = composedSignal;
+    // Body handling — send in order of most specific to least.
+    if (data !== null && data !== undefined) {
+        if (isNativeBodyInit(data)) {
+            // fetch knows how to serialize these and sets Content-Type as needed.
+            init.body = data;
+        }
+        else if (typeof data === "string") {
+            // Raw strings are sent as-is; caller controls Content-Type.
+            init.body = data;
         }
-        // Cover 99% of use cases (may not fit all scenarios)
         else {
-            // If not explicitly stated, assume JSON
-            if (isObj || !normalizedHeaders["content-type"]) {
+            // Plain objects, arrays, numbers, booleans → JSON.
+            if (!normalizedHeaders["content-type"]) {
                 normalizedHeaders["content-type"] = "application/json";
             }
-            opts.body = JSON.stringify(data);
+            init.body = JSON.stringify(data);
         }
     }
     // Opinionated convention: auto-add Bearer token
     if (token) {
         normalizedHeaders["authorization"] = `Bearer ${token}`;
     }
-    opts.headers = normalizedHeaders;
-    return await fetch(path, opts);
-};
-const _fetch = async (params, respHeaders = null, errorMessageExtractor = null, _dumpParams = false) => {
+    init.headers = normalizedHeaders;
+    let url = path;
+    if (query)
+        url = appendQuery(url, query);
+    return { url, init };
+}
+const _fetch = async (params, respHeaders = null, errorMessageExtractor = null, requestInterceptor = null, responseInterceptor = null, _dumpParams = false) => {
     if (_dumpParams)
         return params;
-    const r = await _fetchRaw(params);
+    let { url, init } = buildRequest(params);
+    if (requestInterceptor) {
+        const patched = await requestInterceptor(init, {
+            method: params.method,
+            url,
+        });
+        if (patched)
+            init = patched;
+    }
+    let r = await fetch(url, init);
+    if (responseInterceptor) {
+        const patched = await responseInterceptor(r, {
+            method: params.method,
+            url,
+        });
+        if (patched && patched !== r) {
+            // Cancel the original body so the underlying stream doesn't leak.
+            try {
+                await r.body?.cancel();
+            }
+            catch (_e) { /* ignore */ }
+            r = patched;
+        }
+    }
     if (params.raw)
         return r;
     // Convert Headers to plain object
@@ -143,34 +246,50 @@ const _fetch = async (params, respHeaders = null, errorMessageExtractor = null,
         // Add status/text under special keys
         { __http_status_code__: r.status, __http_status_text__: r.statusText });
     }
-    let body = await r.text();
-    // prettier-ignore
-    try {
-        body = JSON.parse(body);
+    const text = await r.text();
+    let body = text;
+    if (text === "") {
+        // Treat empty body (204/205 and friends) as null rather than "".
+        body = null;
+    }
+    else {
+        // prettier-ignore
+        try {
+            body = JSON.parse(text);
+        }
+        catch (_e) { /* ignore parse errors */ }
     }
-    catch (_e) { /* ignore parse errors */ }
     params.assert ??= true; // default is true
     if (!r.ok && params.assert) {
-        // now we need to extract error message from an unknown response... this is obviously
-        // impossible unless we know what to expect, but we'll do some educated tries...
-        const extractor = errorMessageExtractor ?? // provided arg
-            createHttpApi.defaultErrorMessageExtractor ?? // static default
-            // educated guess fallback
-            function (_body, _response) {
-                const b = _body;
-                let msg = String(
-                // try opinionated convention first
-                b?.error?.message ||
-                    b?.message ||
-                    b?.error ||
-                    _response?.statusText ||
-                    "Unknown error");
-                if (msg.length > 255)
-                    msg = `[Shortened]: ${msg.slice(0, 255)}`;
-                return msg;
-            };
-        // adding `cause` describing more details
-        throw createHttpError(r.status, extractor(body, r), body, {
+        // Now we need to extract an error message from an unknown response shape.
+        // We try, in order: the per-call extractor, the factory/global, and a
+        // built-in guess. If a user-provided extractor throws, we must not let
+        // it replace the real HTTP error — fall back to statusText.
+        const tryExtract = (fn) => {
+            if (!fn)
+                return null;
+            try {
+                return fn(body, r);
+            }
+            catch (_e) {
+                return null;
+            }
+        };
+        const builtIn = (_body, _response) => {
+            const b = _body;
+            let msg = String(b?.error?.message ||
+                b?.message ||
+                b?.error ||
+                _response?.statusText ||
+                "Unknown error");
+            if (msg.length > 255)
+                msg = `[Shortened]: ${msg.slice(0, 255)}`;
+            return msg;
+        };
+        const msg = tryExtract(errorMessageExtractor) ??
+            tryExtract(createHttpApi.defaultErrorMessageExtractor) ??
+            builtIn(body, r);
+        throw createHttpError(r.status, msg, body, {
             method: params.method,
             path: params.path,
             response: {
@@ -189,6 +308,8 @@ export class HttpApi {
     #base;
     #defaults;
     #factoryErrorMessageExtractor;
+    #requestInterceptor;
+    #responseInterceptor;
     constructor(base, defaults, factoryErrorMessageExtractor) {
         this.#base = base;
         this.#defaults = defaults;
@@ -211,54 +332,58 @@ export class HttpApi {
         return { ...(this.#defaults || {}) };
     }
     #buildPath(path, base) {
-        base = `${base || ""}`;
-        path = `${path || ""}`;
-        return /^https?:/.test(path) ? path : base + path;
+        const p = `${path ?? ""}`;
+        const b = `${base ?? ""}`;
+        if (/^https?:/i.test(p))
+            return p;
+        if (!b)
+            return p;
+        const baseNoTrail = b.replace(/\/+$/, "");
+        const pathLead = p.startsWith("/") ? p : `/${p}`;
+        return baseNoTrail + pathLead;
+    }
+    /**
+     * Register a request interceptor. Called after defaults are merged.
+     * Returning a new `RequestInit` replaces the original.
+     */
+    onRequest(interceptor) {
+        this.#requestInterceptor = interceptor;
+        return this;
+    }
+    /**
+     * Register a response interceptor. Called before the body is consumed.
+     * Must not consume the body. Returning a new `Response` replaces the original.
+     */
+    onResponse(interceptor) {
+        this.#responseInterceptor = interceptor;
+        return this;
     }
     async get(path, paramsOrOptions, respHeaders, errorMessageExtractor, _dumpParams = false) {
         const { params, respHeaders: headers, errorExtractor, } = parseGetOptions(paramsOrOptions, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), { ...params, method: "GET", path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return _fetch(this.#merge(await this.#getDefs(), { ...params, method: "GET", path }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, this.#requestInterceptor, this.#responseInterceptor, _dumpParams);
     }
     async post(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        const { data, params: fetchParams, respHeaders: headers, errorExtractor, } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
-        path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), {
-            ...(fetchParams || {}),
-            data,
-            method: "POST",
-            path,
-        }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return await this.#body("POST", path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams);
     }
     async put(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        const { data, params: fetchParams, respHeaders: headers, errorExtractor, } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
-        path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), {
-            ...(fetchParams || {}),
-            data,
-            method: "PUT",
-            path,
-        }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return await this.#body("PUT", path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams);
     }
     async patch(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
-        const { data, params: fetchParams, respHeaders: headers, errorExtractor, } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
-        path = this.#buildPath(path, this.#base);
-        return _fetch(this.#merge(await this.#getDefs(), {
-            ...(fetchParams || {}),
-            data,
-            method: "PATCH",
-            path,
-        }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        return await this.#body("PATCH", path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams);
     }
     async del(path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams = false) {
+        return await this.#body("DELETE", path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams);
+    }
+    async #body(method, path, dataOrOptions, params, respHeaders, errorMessageExtractor, _dumpParams) {
         const { data, params: fetchParams, respHeaders: headers, errorExtractor, } = parseDataOptions(dataOrOptions, params, respHeaders, errorMessageExtractor);
         path = this.#buildPath(path, this.#base);
         return _fetch(this.#merge(await this.#getDefs(), {
             ...(fetchParams || {}),
             data,
-            method: "DELETE",
+            method,
             path,
-        }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, _dumpParams);
+        }), headers, errorExtractor ?? this.#factoryErrorMessageExtractor, this.#requestInterceptor, this.#responseInterceptor, _dumpParams);
     }
     /**
      * Helper method to build the full URL from a path.
@@ -306,6 +431,9 @@ export function createHttpApi(base, defaults, factoryErrorMessageExtractor) {
  * Applied to all requests unless overridden at instance or request level.
  * Priority: per-request → per-instance → global → built-in fallback.
  *
+ * A throwing extractor will not crash the call — the next priority level is
+ * used as a fallback.
+ *
  * @example
  * ```ts
  * createHttpApi.defaultErrorMessageExtractor = (body, response) => {

package/dist/mod.d.ts

@@ -21,6 +21,6 @@
  * }
  * ```
  */
-export { HttpApi, createHttpApi, opts, type DataOptions, type GetOptions, type FetchParams, type ErrorMessageExtractor, type ResponseHeaders, type RequestData, } from "./api.js";
+export { HttpApi, createHttpApi, opts, type DataOptions, type GetOptions, type FetchParams, type ErrorMessageExtractor, type ResponseHeaders, type RequestData, type QueryValue, type RequestInterceptor, type ResponseInterceptor, } from "./api.js";
 export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
 export { HTTP_STATUS } from "./status.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "2.5.0",
+	"version": "2.6.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -10,6 +10,14 @@
 			"import": "./dist/mod.js"
 		}
 	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md",
+		"CLAUDE.md"
+	],
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {},