@danmat/query-fetch 0.1.2 → 0.3.0

package/README.md

@@ -39,6 +39,7 @@ Scripted `fetch(url, { method: "QUERY", body })` already works in modern runtime
 - ✅ **Enforces `Content-Type`** — the RFC requires servers to reject a QUERY whose body has no content type. We throw *before* the round-trip instead of letting you debug a `400`.
 - ✅ **Transparent `POST` fallback** — servers that don't understand QUERY yet respond `405`/`501`; we automatically retry as `POST` and advertise the original method via `X-HTTP-Method-Override` so override-aware backends still route it correctly.
 - ✅ **`Accept` negotiation** — pass a media type (or list) to negotiate the response format the RFC's `Accept-Query` dance is built around.
+- ✅ **Safe automatic retry** (opt-in) — QUERY is *idempotent by definition*, so retrying transient failures is safe here in a way it never is for `POST`. Exponential backoff + jitter, honours `Retry-After`.
 - ✅ **Redirect-safe** — the RFC's `303 See Other` indirect-result pattern is handled by `fetch`'s own redirect following; nothing surprising here.
 - ✅ **Zero dependencies, fully typed, tree-shakeable**, dual ESM/CJS.
 
@@ -69,12 +70,59 @@ await query("https://api.example.com/search", {
 });
 ```
 
+### Automatic retry (safe, because QUERY is idempotent)
+
+RFC 10008 defines QUERY as safe and idempotent — so unlike `POST`, retrying a
+failed request can't cause a double-effect. Opt in with a count, or an object
+for full control:
+
+```ts
+// Retry up to 3 times with exponential backoff + jitter.
+await query(url, { json, retry: 3 });
+
+// Full control.
+await query(url, {
+  json,
+  retry: {
+    retries: 5,
+    minDelay: 200, // base backoff (ms)
+    maxDelay: 10_000,
+    factor: 2,
+    jitter: true,
+    respectRetryAfter: true, // honour Retry-After on 429/503
+    retryOn: ({ response, error }) =>
+      Boolean(error) || (response?.status ?? 0) >= 500,
+    onRetry: ({ attempt, delay }) => console.warn(`retry #${attempt} in ${delay}ms`),
+  },
+});
+```
+
+By default it retries network errors and `408/425/429/500/502/503/504`, and
+does **not** retry aborts. Retry is off unless you set it. (Retries reuse a
+buffered body — a string, bytes, or `json`; a streaming body is sent once.)
+
 ### Opt out of the POST fallback
 
 ```ts
 await query(url, { json, fallbackToPost: false });
 ```
 
+### Force POST override for an origin you know rejects QUERY
+
+The automatic fallback only triggers when the server *answers* `405`/`501`. Some
+origins reject QUERY *before* that — a legacy proxy, or a cross-origin server whose
+CORS allows POST but not QUERY yet — so the QUERY throws (or its preflight fails)
+with no status to react to. When you already know an origin is like that, skip the
+doomed QUERY and POST with the override from the start:
+
+```ts
+await query(url, { json, transport: "post-override" });
+```
+
+This is a deliberate, per-call opt-in. The library never switches to it on its own,
+because a POST is treated as unsafe and uncacheable by intermediaries unless the
+server honors the override — so the choice stays yours.
+
 ### Bring your own `fetch`
 
 ```ts
@@ -97,6 +145,8 @@ Performs a QUERY request. `options` extends `RequestInit` (so `signal`, `credent
 | `accept` | `string \| string[]` | — | Sets the `Accept` header. |
 | `fallbackToPost` | `boolean` | `true` | Retry as `POST` on `405`/`501`. |
 | `methodOverrideHeader` | `string \| false` | `"X-HTTP-Method-Override"` | Header advertising the original method on fallback. |
+| `transport` | `"query" \| "post-override"` | `"query"` | `"post-override"` sends `POST` + override from the start, for an origin you already know rejects QUERY. |
+| `retry` | `number \| RetryOptions` | off | Auto-retry transient failures (safe: QUERY is idempotent). |
 | `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation. |
 
 ### `queryJson<T>(input, options?): Promise<{ data: T; response: Response }>`
@@ -111,7 +161,7 @@ Thrown for construction-time problems (a body without a content type, no availab
 
 QUERY is a **Proposed Standard** (June 2026). Two things to know:
 
-- **CORS:** QUERY is not a CORS-safelisted method, so a cross-origin QUERY triggers a preflight. Your server must handle `OPTIONS` accordingly.
+- **CORS:** QUERY is not a CORS-safelisted method, so a cross-origin QUERY triggers a preflight, and the browser blocks it unless the server returns `QUERY` in `Access-Control-Allow-Methods`. When it doesn't, `fetch` throws with no status, so the automatic `405`/`501` fallback can't see it. For an origin you know is in that state, pass `transport: "post-override"` to POST from the start — provided that server allows `POST` (and the override header) via CORS. There is no client-only way around a server that CORS-blocks both.
 - **Spec churn:** browser-integration details (method normalization, caching) are still being ironed out in [whatwg/fetch#1938](https://github.com/whatwg/fetch/issues/1938). This library tracks runtime behavior as it ships.
 
 ## The `@danmat` QUERY suite

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 // src/index.ts
 var METHOD_UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([405, 501]);
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
 var DEFAULT_OVERRIDE_HEADER = "X-HTTP-Method-Override";
 var QueryError = class _QueryError extends Error {
   name = "QueryError";
@@ -42,6 +43,70 @@ function prepare(options) {
   }
   return { headers, body };
 }
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && error.name === "AbortError";
+}
+function defaultRetryOn(context) {
+  if (context.error !== void 0) return !isAbortError(context.error);
+  if (context.response) return RETRYABLE_STATUSES.has(context.response.status);
+  return false;
+}
+function resolveRetry(retry) {
+  if (retry === void 0) return null;
+  const opts = typeof retry === "number" ? { retries: retry } : retry;
+  if (!opts.retries || opts.retries < 1) return null;
+  return {
+    retries: opts.retries,
+    minDelay: opts.minDelay ?? 200,
+    maxDelay: opts.maxDelay ?? 1e4,
+    factor: opts.factor ?? 2,
+    jitter: opts.jitter ?? true,
+    respectRetryAfter: opts.respectRetryAfter ?? true,
+    retryOn: opts.retryOn ?? defaultRetryOn,
+    onRetry: opts.onRetry
+  };
+}
+function parseRetryAfter(value) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(value);
+  if (Number.isNaN(date)) return null;
+  return Math.max(0, date - Date.now());
+}
+function backoffDelay(cfg, attemptIndex, response) {
+  if (cfg.respectRetryAfter && response) {
+    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+    if (retryAfter !== null) return retryAfter;
+  }
+  const base = Math.min(
+    cfg.maxDelay,
+    cfg.minDelay * cfg.factor ** attemptIndex
+  );
+  return cfg.jitter ? base / 2 + Math.random() * (base / 2) : base;
+}
+function abortError() {
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(abortError());
+      },
+      { once: true }
+    );
+  });
+}
 async function query(input, options = {}) {
   const doFetch = resolveFetch(options.fetch);
   const { headers, body } = prepare(options);
@@ -50,31 +115,63 @@ async function query(input, options = {}) {
     json: _json,
     contentType: _contentType,
     accept: _accept,
+    retry: _retry,
     fallbackToPost = true,
     methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,
+    transport = "query",
     headers: _headers,
     body: _body,
     ...init
   } = options;
-  const response = await doFetch(input, {
-    ...init,
-    method: "QUERY",
-    headers,
-    body
-  });
-  if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {
-    return response;
-  }
-  const fallbackHeaders = new Headers(headers);
-  if (methodOverrideHeader) {
-    fallbackHeaders.set(methodOverrideHeader, "QUERY");
+  const postOverride = () => {
+    const overrideHeaders = new Headers(headers);
+    if (methodOverrideHeader) {
+      overrideHeaders.set(methodOverrideHeader, "QUERY");
+    }
+    return doFetch(input, {
+      ...init,
+      method: "POST",
+      headers: overrideHeaders,
+      body
+    });
+  };
+  const attempt = async () => {
+    if (transport === "post-override") return postOverride();
+    const response = await doFetch(input, {
+      ...init,
+      method: "QUERY",
+      headers,
+      body
+    });
+    if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {
+      return response;
+    }
+    return postOverride();
+  };
+  const retryCfg = resolveRetry(options.retry);
+  if (!retryCfg) return attempt();
+  const signal = init.signal ?? null;
+  for (let i = 0; ; i++) {
+    let response;
+    let caught;
+    try {
+      response = await attempt();
+    } catch (error) {
+      caught = error;
+    }
+    const isLastAttempt = i >= retryCfg.retries;
+    const context = { attempt: i + 1, response, error: caught };
+    if (caught !== void 0) {
+      if (isLastAttempt || isAbortError(caught) || !await retryCfg.retryOn(context)) {
+        throw caught;
+      }
+    } else if (isLastAttempt || !await retryCfg.retryOn(context)) {
+      return response;
+    }
+    const delay = backoffDelay(retryCfg, i, response);
+    retryCfg.onRetry?.({ ...context, delay });
+    await sleep(delay, signal);
   }
-  return doFetch(input, {
-    ...init,
-    method: "POST",
-    headers: fallbackHeaders,
-    body
-  });
 }
 async function queryJson(input, options = {}) {
   const response = await query(input, {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @danmat/query-fetch\n *\n * A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the\n * safe, idempotent request that carries a body like POST but caches like GET.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\n/** Status codes that signal a server does not understand the QUERY method. */\nconst METHOD_UNSUPPORTED_STATUSES = new Set([405, 501]);\n\n/** Default header used to tunnel the intended method when falling back to POST. */\nconst DEFAULT_OVERRIDE_HEADER = \"X-HTTP-Method-Override\";\n\n/**\n * Error thrown when a QUERY request cannot be constructed according to the\n * requirements of RFC 10008 (e.g. a body with no `Content-Type`).\n */\nexport class QueryError extends Error {\n  override name = \"QueryError\";\n\n  constructor(message: string) {\n    super(message);\n    // Restore prototype chain for transpiled/ES5 targets.\n    Object.setPrototypeOf(this, QueryError.prototype);\n  }\n}\n\n/** Options for {@link query}. Extends `RequestInit` minus the fields we own. */\nexport interface QueryOptions extends Omit<RequestInit, \"method\" | \"body\"> {\n  /**\n   * The raw query body. Pair with {@link QueryOptions.contentType}. For JSON\n   * payloads prefer {@link QueryOptions.json}, which sets the content type for\n   * you.\n   */\n  body?: BodyInit | null;\n\n  /**\n   * Convenience: a value serialized to JSON and sent as\n   * `application/json`. Ignored if {@link QueryOptions.body} is set.\n   */\n  json?: unknown;\n\n  /**\n   * MIME type of the query body. **Required** whenever a body is present —\n   * RFC 10008 mandates that servers reject a QUERY with a missing or\n   * inconsistent `Content-Type`. Ignored when using {@link QueryOptions.json}.\n   */\n  contentType?: string;\n\n  /** Media type(s) acceptable in the response. Sets the `Accept` header. */\n  accept?: string | string[];\n\n  /**\n   * Retry as `POST` when the server reports it does not support QUERY\n   * (HTTP 405 or 501). Defaults to `true`.\n   */\n  fallbackToPost?: boolean;\n\n  /**\n   * Header name used to advertise the original method on a POST fallback so\n   * that override-aware servers can still route it as a QUERY. Set to `false`\n   * to disable. Defaults to `\"X-HTTP-Method-Override\"`.\n   */\n  methodOverrideHeader?: string | false;\n\n  /**\n   * A `fetch` implementation to use instead of the global. Handy for testing\n   * or for runtimes that expose `fetch` on a client rather than globally.\n   */\n  fetch?: typeof fetch;\n}\n\n/** The result of {@link queryJson}: a parsed body plus the originating response. */\nexport interface QueryJsonResult<T> {\n  data: T;\n  response: Response;\n}\n\nfunction resolveFetch(custom?: typeof fetch): typeof fetch {\n  const impl = custom ?? globalThis.fetch;\n  if (typeof impl !== \"function\") {\n    throw new QueryError(\n      \"No fetch implementation found. Pass `fetch` in options or run on a runtime that provides a global fetch.\",\n    );\n  }\n  return impl;\n}\n\n/**\n * Build the request body and headers, enforcing RFC 10008's `Content-Type`\n * requirement. Returns the effective body so it can be reused by a fallback.\n */\nfunction prepare(options: QueryOptions): {\n  headers: Headers;\n  body: BodyInit | null | undefined;\n} {\n  const headers = new Headers(options.headers);\n\n  let body: BodyInit | null | undefined = options.body;\n\n  if (body == null && options.json !== undefined) {\n    body = JSON.stringify(options.json);\n    if (!headers.has(\"content-type\")) {\n      headers.set(\"content-type\", \"application/json\");\n    }\n  } else if (options.contentType) {\n    headers.set(\"content-type\", options.contentType);\n  }\n\n  const hasBody = body != null;\n  if (hasBody && !headers.has(\"content-type\")) {\n    throw new QueryError(\n      \"A QUERY request with a body must set a Content-Type (RFC 10008). Pass `contentType`, use `json`, or set the header explicitly.\",\n    );\n  }\n\n  if (options.accept !== undefined) {\n    const accept = Array.isArray(options.accept)\n      ? options.accept.join(\", \")\n      : options.accept;\n    headers.set(\"accept\", accept);\n  }\n\n  return { headers, body };\n}\n\n/**\n * Perform an HTTP QUERY request (RFC 10008).\n *\n * QUERY is safe and idempotent like GET, but carries a request body like POST,\n * making it ideal for large or structured queries that don't fit in a URL.\n *\n * Redirects — including the RFC's `303 See Other` indirect-result pattern — are\n * handled by the underlying `fetch` per the request's `redirect` mode (default\n * `\"follow\"`), so no special handling is needed here.\n *\n * @example\n * ```ts\n * const res = await query(\"https://api.example.com/search\", {\n *   json: { filter: { status: \"active\" }, sort: \"-createdAt\" },\n *   accept: \"application/json\",\n * });\n * ```\n */\nexport async function query(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<Response> {\n  const doFetch = resolveFetch(options.fetch);\n  const { headers, body } = prepare(options);\n\n  const {\n    fetch: _fetch,\n    json: _json,\n    contentType: _contentType,\n    accept: _accept,\n    fallbackToPost = true,\n    methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,\n    headers: _headers,\n    body: _body,\n    ...init\n  } = options;\n\n  const response = await doFetch(input, {\n    ...init,\n    method: \"QUERY\",\n    headers,\n    body,\n  });\n\n  if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {\n    return response;\n  }\n\n  // The server doesn't speak QUERY — retry as POST, optionally advertising the\n  // original method so override-aware servers can still treat it as a query.\n  const fallbackHeaders = new Headers(headers);\n  if (methodOverrideHeader) {\n    fallbackHeaders.set(methodOverrideHeader, \"QUERY\");\n  }\n\n  return doFetch(input, {\n    ...init,\n    method: \"POST\",\n    headers: fallbackHeaders,\n    body,\n  });\n}\n\n/**\n * Like {@link query}, but parses the response body as JSON.\n *\n * Throws {@link QueryError} on a non-2xx response so callers don't silently\n * parse an error page.\n */\nexport async function queryJson<T = unknown>(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<QueryJsonResult<T>> {\n  const response = await query(input, {\n    accept: \"application/json\",\n    ...options,\n  });\n\n  if (!response.ok) {\n    throw new QueryError(\n      `QUERY ${input.toString()} failed with status ${response.status} ${response.statusText}`,\n    );\n  }\n\n  return { data: (await response.json()) as T, response };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @danmat/query-fetch\n *\n * A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the\n * safe, idempotent request that carries a body like POST but caches like GET.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\n/** Status codes that signal a server does not understand the QUERY method. */\nconst METHOD_UNSUPPORTED_STATUSES = new Set([405, 501]);\n\n/** Statuses worth retrying for an idempotent request. */\nconst RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);\n\n/** Default header used to tunnel the intended method when falling back to POST. */\nconst DEFAULT_OVERRIDE_HEADER = \"X-HTTP-Method-Override\";\n\n/**\n * Error thrown when a QUERY request cannot be constructed according to the\n * requirements of RFC 10008 (e.g. a body with no `Content-Type`).\n */\nexport class QueryError extends Error {\n  override name = \"QueryError\";\n\n  constructor(message: string) {\n    super(message);\n    // Restore prototype chain for transpiled/ES5 targets.\n    Object.setPrototypeOf(this, QueryError.prototype);\n  }\n}\n\n/** Details about a failed attempt, passed to retry callbacks. */\nexport interface RetryContext {\n  /** 1-based number of the retry about to happen (or being decided). */\n  attempt: number;\n  /** The response received, when the failure was an HTTP status. */\n  response?: Response;\n  /** The error thrown, when the failure was a network/abort error. */\n  error?: unknown;\n}\n\n/** Controls automatic retries. See {@link QueryOptions.retry}. */\nexport interface RetryOptions {\n  /** Maximum number of retries after the initial attempt. */\n  retries: number;\n  /** Base backoff delay in milliseconds. Default `200`. */\n  minDelay?: number;\n  /** Maximum backoff delay in milliseconds. Default `10000`. */\n  maxDelay?: number;\n  /** Exponential backoff multiplier. Default `2`. */\n  factor?: number;\n  /** Apply random jitter to spread retries out. Default `true`. */\n  jitter?: boolean;\n  /** Honor a `Retry-After` response header (e.g. on 429/503). Default `true`. */\n  respectRetryAfter?: boolean;\n  /**\n   * Decide whether a failed attempt should be retried. By default, network\n   * errors and the statuses 408/425/429/500/502/503/504 are retried, while\n   * aborts are not. QUERY is idempotent, so retrying is safe.\n   */\n  retryOn?: (context: RetryContext) => boolean | Promise<boolean>;\n  /** Called before each backoff wait, with the chosen delay. */\n  onRetry?: (context: RetryContext & { delay: number }) => void;\n}\n\n/** Options for {@link query}. Extends `RequestInit` minus the fields we own. */\nexport interface QueryOptions extends Omit<RequestInit, \"method\" | \"body\"> {\n  /**\n   * The raw query body. Pair with {@link QueryOptions.contentType}. For JSON\n   * payloads prefer {@link QueryOptions.json}, which sets the content type for\n   * you.\n   */\n  body?: BodyInit | null;\n\n  /**\n   * Convenience: a value serialized to JSON and sent as\n   * `application/json`. Ignored if {@link QueryOptions.body} is set.\n   */\n  json?: unknown;\n\n  /**\n   * MIME type of the query body. **Required** whenever a body is present —\n   * RFC 10008 mandates that servers reject a QUERY with a missing or\n   * inconsistent `Content-Type`. Ignored when using {@link QueryOptions.json}.\n   */\n  contentType?: string;\n\n  /** Media type(s) acceptable in the response. Sets the `Accept` header. */\n  accept?: string | string[];\n\n  /**\n   * Retry as `POST` when the server reports it does not support QUERY\n   * (HTTP 405 or 501). Defaults to `true`.\n   */\n  fallbackToPost?: boolean;\n\n  /**\n   * Header name used to advertise the original method on a POST fallback so\n   * that override-aware servers can still route it as a QUERY. Set to `false`\n   * to disable. Defaults to `\"X-HTTP-Method-Override\"`.\n   */\n  methodOverrideHeader?: string | false;\n\n  /**\n   * How to reach a server that may not support QUERY.\n   *\n   * - `\"query\"` (default): send a real QUERY, and — when {@link fallbackToPost}\n   *   is on — fall back to POST only if the server *answers* `405`/`501`.\n   * - `\"post-override\"`: skip QUERY entirely and send POST from the start, with\n   *   the intended method advertised via {@link methodOverrideHeader}. Use this\n   *   for an origin you already know rejects QUERY *before* a clean status comes\n   *   back — a legacy proxy, or a cross-origin server whose CORS allows POST but\n   *   not QUERY yet — where a real QUERY would only fail after a wasted round\n   *   trip (or a CORS preflight the client can't see). This is a deliberate\n   *   opt-in: the request goes out as a POST, so intermediaries treat it as\n   *   unsafe and uncacheable unless the server honors the override. The library\n   *   never switches to this on its own — you decide, per call.\n   */\n  transport?: \"query\" | \"post-override\";\n\n  /**\n   * Automatically retry transient failures. Pass a number for \"retry N times\n   * with sensible backoff\", or a {@link RetryOptions} object for full control.\n   * Because QUERY is idempotent, retrying is safe — unlike POST. Off unless set.\n   *\n   * Retries reuse a buffered body (a string, bytes, or `json`); a streaming\n   * body can only be sent once and won't be retried.\n   */\n  retry?: number | RetryOptions;\n\n  /**\n   * A `fetch` implementation to use instead of the global. Handy for testing\n   * or for runtimes that expose `fetch` on a client rather than globally.\n   */\n  fetch?: typeof fetch;\n}\n\n/** The result of {@link queryJson}: a parsed body plus the originating response. */\nexport interface QueryJsonResult<T> {\n  data: T;\n  response: Response;\n}\n\ninterface ResolvedRetry {\n  retries: number;\n  minDelay: number;\n  maxDelay: number;\n  factor: number;\n  jitter: boolean;\n  respectRetryAfter: boolean;\n  retryOn: (context: RetryContext) => boolean | Promise<boolean>;\n  onRetry?: (context: RetryContext & { delay: number }) => void;\n}\n\nfunction resolveFetch(custom?: typeof fetch): typeof fetch {\n  const impl = custom ?? globalThis.fetch;\n  if (typeof impl !== \"function\") {\n    throw new QueryError(\n      \"No fetch implementation found. Pass `fetch` in options or run on a runtime that provides a global fetch.\",\n    );\n  }\n  return impl;\n}\n\n/**\n * Build the request body and headers, enforcing RFC 10008's `Content-Type`\n * requirement. Returns the effective body so it can be reused by a fallback.\n */\nfunction prepare(options: QueryOptions): {\n  headers: Headers;\n  body: BodyInit | null | undefined;\n} {\n  const headers = new Headers(options.headers);\n\n  let body: BodyInit | null | undefined = options.body;\n\n  if (body == null && options.json !== undefined) {\n    body = JSON.stringify(options.json);\n    if (!headers.has(\"content-type\")) {\n      headers.set(\"content-type\", \"application/json\");\n    }\n  } else if (options.contentType) {\n    headers.set(\"content-type\", options.contentType);\n  }\n\n  const hasBody = body != null;\n  if (hasBody && !headers.has(\"content-type\")) {\n    throw new QueryError(\n      \"A QUERY request with a body must set a Content-Type (RFC 10008). Pass `contentType`, use `json`, or set the header explicitly.\",\n    );\n  }\n\n  if (options.accept !== undefined) {\n    const accept = Array.isArray(options.accept)\n      ? options.accept.join(\", \")\n      : options.accept;\n    headers.set(\"accept\", accept);\n  }\n\n  return { headers, body };\n}\n\nfunction isAbortError(error: unknown): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    (error as { name?: string }).name === \"AbortError\"\n  );\n}\n\nfunction defaultRetryOn(context: RetryContext): boolean {\n  if (context.error !== undefined) return !isAbortError(context.error);\n  if (context.response) return RETRYABLE_STATUSES.has(context.response.status);\n  return false;\n}\n\nfunction resolveRetry(\n  retry: number | RetryOptions | undefined,\n): ResolvedRetry | null {\n  if (retry === undefined) return null;\n  const opts = typeof retry === \"number\" ? { retries: retry } : retry;\n  if (!opts.retries || opts.retries < 1) return null;\n  return {\n    retries: opts.retries,\n    minDelay: opts.minDelay ?? 200,\n    maxDelay: opts.maxDelay ?? 10_000,\n    factor: opts.factor ?? 2,\n    jitter: opts.jitter ?? true,\n    respectRetryAfter: opts.respectRetryAfter ?? true,\n    retryOn: opts.retryOn ?? defaultRetryOn,\n    onRetry: opts.onRetry,\n  };\n}\n\nfunction parseRetryAfter(value: string | null): number | null {\n  if (!value) return null;\n  const seconds = Number(value);\n  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);\n  const date = Date.parse(value);\n  if (Number.isNaN(date)) return null;\n  return Math.max(0, date - Date.now());\n}\n\nfunction backoffDelay(\n  cfg: ResolvedRetry,\n  attemptIndex: number,\n  response?: Response,\n): number {\n  if (cfg.respectRetryAfter && response) {\n    const retryAfter = parseRetryAfter(response.headers.get(\"retry-after\"));\n    if (retryAfter !== null) return retryAfter;\n  }\n  const base = Math.min(\n    cfg.maxDelay,\n    cfg.minDelay * cfg.factor ** attemptIndex,\n  );\n  return cfg.jitter ? base / 2 + Math.random() * (base / 2) : base;\n}\n\nfunction abortError(): Error {\n  const error = new Error(\"The operation was aborted.\");\n  error.name = \"AbortError\";\n  return error;\n}\n\nfunction sleep(ms: number, signal?: AbortSignal | null): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(abortError());\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\n      \"abort\",\n      () => {\n        clearTimeout(timer);\n        reject(abortError());\n      },\n      { once: true },\n    );\n  });\n}\n\n/**\n * Perform an HTTP QUERY request (RFC 10008).\n *\n * QUERY is safe and idempotent like GET, but carries a request body like POST,\n * making it ideal for large or structured queries that don't fit in a URL.\n *\n * Redirects — including the RFC's `303 See Other` indirect-result pattern — are\n * handled by the underlying `fetch` per the request's `redirect` mode (default\n * `\"follow\"`), so no special handling is needed here.\n *\n * @example\n * ```ts\n * const res = await query(\"https://api.example.com/search\", {\n *   json: { filter: { status: \"active\" }, sort: \"-createdAt\" },\n *   accept: \"application/json\",\n *   retry: 3, // safe: QUERY is idempotent\n * });\n * ```\n */\nexport async function query(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<Response> {\n  const doFetch = resolveFetch(options.fetch);\n  const { headers, body } = prepare(options);\n\n  const {\n    fetch: _fetch,\n    json: _json,\n    contentType: _contentType,\n    accept: _accept,\n    retry: _retry,\n    fallbackToPost = true,\n    methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,\n    transport = \"query\",\n    headers: _headers,\n    body: _body,\n    ...init\n  } = options;\n\n  // POST carrying the original method in an override header, for a server that\n  // doesn't speak QUERY. Shared by the explicit `transport: \"post-override\"`\n  // mode and the automatic 405/501 fallback below.\n  const postOverride = (): Promise<Response> => {\n    const overrideHeaders = new Headers(headers);\n    if (methodOverrideHeader) {\n      overrideHeaders.set(methodOverrideHeader, \"QUERY\");\n    }\n    return doFetch(input, {\n      ...init,\n      method: \"POST\",\n      headers: overrideHeaders,\n      body,\n    });\n  };\n\n  const attempt = async (): Promise<Response> => {\n    // Caller already knows this origin won't accept a QUERY: don't waste the\n    // round trip, POST with the override from the start.\n    if (transport === \"post-override\") return postOverride();\n\n    const response = await doFetch(input, {\n      ...init,\n      method: \"QUERY\",\n      headers,\n      body,\n    });\n\n    // The server *answered* that it doesn't speak QUERY — fall back to POST,\n    // advertising the original method so override-aware servers still treat it\n    // as one. Only fires on an explicit 405/501, never on an opaque throw.\n    if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {\n      return response;\n    }\n    return postOverride();\n  };\n\n  const retryCfg = resolveRetry(options.retry);\n  if (!retryCfg) return attempt();\n\n  const signal = init.signal ?? null;\n  for (let i = 0; ; i++) {\n    let response: Response | undefined;\n    let caught: unknown;\n    try {\n      response = await attempt();\n    } catch (error) {\n      caught = error;\n    }\n\n    const isLastAttempt = i >= retryCfg.retries;\n    const context: RetryContext = { attempt: i + 1, response, error: caught };\n\n    if (caught !== undefined) {\n      if (\n        isLastAttempt ||\n        isAbortError(caught) ||\n        !(await retryCfg.retryOn(context))\n      ) {\n        throw caught;\n      }\n    } else if (isLastAttempt || !(await retryCfg.retryOn(context))) {\n      return response as Response;\n    }\n\n    const delay = backoffDelay(retryCfg, i, response);\n    retryCfg.onRetry?.({ ...context, delay });\n    await sleep(delay, signal);\n  }\n}\n\n/**\n * Like {@link query}, but parses the response body as JSON.\n *\n * Throws {@link QueryError} on a non-2xx response so callers don't silently\n * parse an error page.\n */\nexport async function queryJson<T = unknown>(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<QueryJsonResult<T>> {\n  const response = await query(input, {\n    accept: \"application/json\",\n    ...options,\n  });\n\n  if (!response.ok) {\n    throw new QueryError(\n      `QUERY ${input.toString()} failed with status ${response.status} ${response.statusText}`,\n    );\n  }\n\n  return { data: (await response.json()) as T, response };\n}\n"]}

package/dist/index.d.cts

@@ -14,6 +14,40 @@ declare class QueryError extends Error {
     name: string;
     constructor(message: string);
 }
+/** Details about a failed attempt, passed to retry callbacks. */
+interface RetryContext {
+    /** 1-based number of the retry about to happen (or being decided). */
+    attempt: number;
+    /** The response received, when the failure was an HTTP status. */
+    response?: Response;
+    /** The error thrown, when the failure was a network/abort error. */
+    error?: unknown;
+}
+/** Controls automatic retries. See {@link QueryOptions.retry}. */
+interface RetryOptions {
+    /** Maximum number of retries after the initial attempt. */
+    retries: number;
+    /** Base backoff delay in milliseconds. Default `200`. */
+    minDelay?: number;
+    /** Maximum backoff delay in milliseconds. Default `10000`. */
+    maxDelay?: number;
+    /** Exponential backoff multiplier. Default `2`. */
+    factor?: number;
+    /** Apply random jitter to spread retries out. Default `true`. */
+    jitter?: boolean;
+    /** Honor a `Retry-After` response header (e.g. on 429/503). Default `true`. */
+    respectRetryAfter?: boolean;
+    /**
+     * Decide whether a failed attempt should be retried. By default, network
+     * errors and the statuses 408/425/429/500/502/503/504 are retried, while
+     * aborts are not. QUERY is idempotent, so retrying is safe.
+     */
+    retryOn?: (context: RetryContext) => boolean | Promise<boolean>;
+    /** Called before each backoff wait, with the chosen delay. */
+    onRetry?: (context: RetryContext & {
+        delay: number;
+    }) => void;
+}
 /** Options for {@link query}. Extends `RequestInit` minus the fields we own. */
 interface QueryOptions extends Omit<RequestInit, "method" | "body"> {
     /**
@@ -46,6 +80,31 @@ interface QueryOptions extends Omit<RequestInit, "method" | "body"> {
      * to disable. Defaults to `"X-HTTP-Method-Override"`.
      */
     methodOverrideHeader?: string | false;
+    /**
+     * How to reach a server that may not support QUERY.
+     *
+     * - `"query"` (default): send a real QUERY, and — when {@link fallbackToPost}
+     *   is on — fall back to POST only if the server *answers* `405`/`501`.
+     * - `"post-override"`: skip QUERY entirely and send POST from the start, with
+     *   the intended method advertised via {@link methodOverrideHeader}. Use this
+     *   for an origin you already know rejects QUERY *before* a clean status comes
+     *   back — a legacy proxy, or a cross-origin server whose CORS allows POST but
+     *   not QUERY yet — where a real QUERY would only fail after a wasted round
+     *   trip (or a CORS preflight the client can't see). This is a deliberate
+     *   opt-in: the request goes out as a POST, so intermediaries treat it as
+     *   unsafe and uncacheable unless the server honors the override. The library
+     *   never switches to this on its own — you decide, per call.
+     */
+    transport?: "query" | "post-override";
+    /**
+     * Automatically retry transient failures. Pass a number for "retry N times
+     * with sensible backoff", or a {@link RetryOptions} object for full control.
+     * Because QUERY is idempotent, retrying is safe — unlike POST. Off unless set.
+     *
+     * Retries reuse a buffered body (a string, bytes, or `json`); a streaming
+     * body can only be sent once and won't be retried.
+     */
+    retry?: number | RetryOptions;
     /**
      * A `fetch` implementation to use instead of the global. Handy for testing
      * or for runtimes that expose `fetch` on a client rather than globally.
@@ -72,6 +131,7 @@ interface QueryJsonResult<T> {
  * const res = await query("https://api.example.com/search", {
  *   json: { filter: { status: "active" }, sort: "-createdAt" },
  *   accept: "application/json",
+ *   retry: 3, // safe: QUERY is idempotent
  * });
  * ```
  */
@@ -84,4 +144,4 @@ declare function query(input: string | URL, options?: QueryOptions): Promise<Res
  */
 declare function queryJson<T = unknown>(input: string | URL, options?: QueryOptions): Promise<QueryJsonResult<T>>;
 
-export { QueryError, type QueryJsonResult, type QueryOptions, query, queryJson };
+export { QueryError, type QueryJsonResult, type QueryOptions, type RetryContext, type RetryOptions, query, queryJson };

package/dist/index.d.ts

@@ -14,6 +14,40 @@ declare class QueryError extends Error {
     name: string;
     constructor(message: string);
 }
+/** Details about a failed attempt, passed to retry callbacks. */
+interface RetryContext {
+    /** 1-based number of the retry about to happen (or being decided). */
+    attempt: number;
+    /** The response received, when the failure was an HTTP status. */
+    response?: Response;
+    /** The error thrown, when the failure was a network/abort error. */
+    error?: unknown;
+}
+/** Controls automatic retries. See {@link QueryOptions.retry}. */
+interface RetryOptions {
+    /** Maximum number of retries after the initial attempt. */
+    retries: number;
+    /** Base backoff delay in milliseconds. Default `200`. */
+    minDelay?: number;
+    /** Maximum backoff delay in milliseconds. Default `10000`. */
+    maxDelay?: number;
+    /** Exponential backoff multiplier. Default `2`. */
+    factor?: number;
+    /** Apply random jitter to spread retries out. Default `true`. */
+    jitter?: boolean;
+    /** Honor a `Retry-After` response header (e.g. on 429/503). Default `true`. */
+    respectRetryAfter?: boolean;
+    /**
+     * Decide whether a failed attempt should be retried. By default, network
+     * errors and the statuses 408/425/429/500/502/503/504 are retried, while
+     * aborts are not. QUERY is idempotent, so retrying is safe.
+     */
+    retryOn?: (context: RetryContext) => boolean | Promise<boolean>;
+    /** Called before each backoff wait, with the chosen delay. */
+    onRetry?: (context: RetryContext & {
+        delay: number;
+    }) => void;
+}
 /** Options for {@link query}. Extends `RequestInit` minus the fields we own. */
 interface QueryOptions extends Omit<RequestInit, "method" | "body"> {
     /**
@@ -46,6 +80,31 @@ interface QueryOptions extends Omit<RequestInit, "method" | "body"> {
      * to disable. Defaults to `"X-HTTP-Method-Override"`.
      */
     methodOverrideHeader?: string | false;
+    /**
+     * How to reach a server that may not support QUERY.
+     *
+     * - `"query"` (default): send a real QUERY, and — when {@link fallbackToPost}
+     *   is on — fall back to POST only if the server *answers* `405`/`501`.
+     * - `"post-override"`: skip QUERY entirely and send POST from the start, with
+     *   the intended method advertised via {@link methodOverrideHeader}. Use this
+     *   for an origin you already know rejects QUERY *before* a clean status comes
+     *   back — a legacy proxy, or a cross-origin server whose CORS allows POST but
+     *   not QUERY yet — where a real QUERY would only fail after a wasted round
+     *   trip (or a CORS preflight the client can't see). This is a deliberate
+     *   opt-in: the request goes out as a POST, so intermediaries treat it as
+     *   unsafe and uncacheable unless the server honors the override. The library
+     *   never switches to this on its own — you decide, per call.
+     */
+    transport?: "query" | "post-override";
+    /**
+     * Automatically retry transient failures. Pass a number for "retry N times
+     * with sensible backoff", or a {@link RetryOptions} object for full control.
+     * Because QUERY is idempotent, retrying is safe — unlike POST. Off unless set.
+     *
+     * Retries reuse a buffered body (a string, bytes, or `json`); a streaming
+     * body can only be sent once and won't be retried.
+     */
+    retry?: number | RetryOptions;
     /**
      * A `fetch` implementation to use instead of the global. Handy for testing
      * or for runtimes that expose `fetch` on a client rather than globally.
@@ -72,6 +131,7 @@ interface QueryJsonResult<T> {
  * const res = await query("https://api.example.com/search", {
  *   json: { filter: { status: "active" }, sort: "-createdAt" },
  *   accept: "application/json",
+ *   retry: 3, // safe: QUERY is idempotent
  * });
  * ```
  */
@@ -84,4 +144,4 @@ declare function query(input: string | URL, options?: QueryOptions): Promise<Res
  */
 declare function queryJson<T = unknown>(input: string | URL, options?: QueryOptions): Promise<QueryJsonResult<T>>;
 
-export { QueryError, type QueryJsonResult, type QueryOptions, query, queryJson };
+export { QueryError, type QueryJsonResult, type QueryOptions, type RetryContext, type RetryOptions, query, queryJson };

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/index.ts
 var METHOD_UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([405, 501]);
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
 var DEFAULT_OVERRIDE_HEADER = "X-HTTP-Method-Override";
 var QueryError = class _QueryError extends Error {
   name = "QueryError";
@@ -40,6 +41,70 @@ function prepare(options) {
   }
   return { headers, body };
 }
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && error.name === "AbortError";
+}
+function defaultRetryOn(context) {
+  if (context.error !== void 0) return !isAbortError(context.error);
+  if (context.response) return RETRYABLE_STATUSES.has(context.response.status);
+  return false;
+}
+function resolveRetry(retry) {
+  if (retry === void 0) return null;
+  const opts = typeof retry === "number" ? { retries: retry } : retry;
+  if (!opts.retries || opts.retries < 1) return null;
+  return {
+    retries: opts.retries,
+    minDelay: opts.minDelay ?? 200,
+    maxDelay: opts.maxDelay ?? 1e4,
+    factor: opts.factor ?? 2,
+    jitter: opts.jitter ?? true,
+    respectRetryAfter: opts.respectRetryAfter ?? true,
+    retryOn: opts.retryOn ?? defaultRetryOn,
+    onRetry: opts.onRetry
+  };
+}
+function parseRetryAfter(value) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(value);
+  if (Number.isNaN(date)) return null;
+  return Math.max(0, date - Date.now());
+}
+function backoffDelay(cfg, attemptIndex, response) {
+  if (cfg.respectRetryAfter && response) {
+    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+    if (retryAfter !== null) return retryAfter;
+  }
+  const base = Math.min(
+    cfg.maxDelay,
+    cfg.minDelay * cfg.factor ** attemptIndex
+  );
+  return cfg.jitter ? base / 2 + Math.random() * (base / 2) : base;
+}
+function abortError() {
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(abortError());
+      },
+      { once: true }
+    );
+  });
+}
 async function query(input, options = {}) {
   const doFetch = resolveFetch(options.fetch);
   const { headers, body } = prepare(options);
@@ -48,31 +113,63 @@ async function query(input, options = {}) {
     json: _json,
     contentType: _contentType,
     accept: _accept,
+    retry: _retry,
     fallbackToPost = true,
     methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,
+    transport = "query",
     headers: _headers,
     body: _body,
     ...init
   } = options;
-  const response = await doFetch(input, {
-    ...init,
-    method: "QUERY",
-    headers,
-    body
-  });
-  if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {
-    return response;
-  }
-  const fallbackHeaders = new Headers(headers);
-  if (methodOverrideHeader) {
-    fallbackHeaders.set(methodOverrideHeader, "QUERY");
+  const postOverride = () => {
+    const overrideHeaders = new Headers(headers);
+    if (methodOverrideHeader) {
+      overrideHeaders.set(methodOverrideHeader, "QUERY");
+    }
+    return doFetch(input, {
+      ...init,
+      method: "POST",
+      headers: overrideHeaders,
+      body
+    });
+  };
+  const attempt = async () => {
+    if (transport === "post-override") return postOverride();
+    const response = await doFetch(input, {
+      ...init,
+      method: "QUERY",
+      headers,
+      body
+    });
+    if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {
+      return response;
+    }
+    return postOverride();
+  };
+  const retryCfg = resolveRetry(options.retry);
+  if (!retryCfg) return attempt();
+  const signal = init.signal ?? null;
+  for (let i = 0; ; i++) {
+    let response;
+    let caught;
+    try {
+      response = await attempt();
+    } catch (error) {
+      caught = error;
+    }
+    const isLastAttempt = i >= retryCfg.retries;
+    const context = { attempt: i + 1, response, error: caught };
+    if (caught !== void 0) {
+      if (isLastAttempt || isAbortError(caught) || !await retryCfg.retryOn(context)) {
+        throw caught;
+      }
+    } else if (isLastAttempt || !await retryCfg.retryOn(context)) {
+      return response;
+    }
+    const delay = backoffDelay(retryCfg, i, response);
+    retryCfg.onRetry?.({ ...context, delay });
+    await sleep(delay, signal);
   }
-  return doFetch(input, {
-    ...init,
-    method: "POST",
-    headers: fallbackHeaders,
-    body
-  });
 }
 async function queryJson(input, options = {}) {
   const response = await query(input, {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @danmat/query-fetch\n *\n * A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the\n * safe, idempotent request that carries a body like POST but caches like GET.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\n/** Status codes that signal a server does not understand the QUERY method. */\nconst METHOD_UNSUPPORTED_STATUSES = new Set([405, 501]);\n\n/** Default header used to tunnel the intended method when falling back to POST. */\nconst DEFAULT_OVERRIDE_HEADER = \"X-HTTP-Method-Override\";\n\n/**\n * Error thrown when a QUERY request cannot be constructed according to the\n * requirements of RFC 10008 (e.g. a body with no `Content-Type`).\n */\nexport class QueryError extends Error {\n  override name = \"QueryError\";\n\n  constructor(message: string) {\n    super(message);\n    // Restore prototype chain for transpiled/ES5 targets.\n    Object.setPrototypeOf(this, QueryError.prototype);\n  }\n}\n\n/** Options for {@link query}. Extends `RequestInit` minus the fields we own. */\nexport interface QueryOptions extends Omit<RequestInit, \"method\" | \"body\"> {\n  /**\n   * The raw query body. Pair with {@link QueryOptions.contentType}. For JSON\n   * payloads prefer {@link QueryOptions.json}, which sets the content type for\n   * you.\n   */\n  body?: BodyInit | null;\n\n  /**\n   * Convenience: a value serialized to JSON and sent as\n   * `application/json`. Ignored if {@link QueryOptions.body} is set.\n   */\n  json?: unknown;\n\n  /**\n   * MIME type of the query body. **Required** whenever a body is present —\n   * RFC 10008 mandates that servers reject a QUERY with a missing or\n   * inconsistent `Content-Type`. Ignored when using {@link QueryOptions.json}.\n   */\n  contentType?: string;\n\n  /** Media type(s) acceptable in the response. Sets the `Accept` header. */\n  accept?: string | string[];\n\n  /**\n   * Retry as `POST` when the server reports it does not support QUERY\n   * (HTTP 405 or 501). Defaults to `true`.\n   */\n  fallbackToPost?: boolean;\n\n  /**\n   * Header name used to advertise the original method on a POST fallback so\n   * that override-aware servers can still route it as a QUERY. Set to `false`\n   * to disable. Defaults to `\"X-HTTP-Method-Override\"`.\n   */\n  methodOverrideHeader?: string | false;\n\n  /**\n   * A `fetch` implementation to use instead of the global. Handy for testing\n   * or for runtimes that expose `fetch` on a client rather than globally.\n   */\n  fetch?: typeof fetch;\n}\n\n/** The result of {@link queryJson}: a parsed body plus the originating response. */\nexport interface QueryJsonResult<T> {\n  data: T;\n  response: Response;\n}\n\nfunction resolveFetch(custom?: typeof fetch): typeof fetch {\n  const impl = custom ?? globalThis.fetch;\n  if (typeof impl !== \"function\") {\n    throw new QueryError(\n      \"No fetch implementation found. Pass `fetch` in options or run on a runtime that provides a global fetch.\",\n    );\n  }\n  return impl;\n}\n\n/**\n * Build the request body and headers, enforcing RFC 10008's `Content-Type`\n * requirement. Returns the effective body so it can be reused by a fallback.\n */\nfunction prepare(options: QueryOptions): {\n  headers: Headers;\n  body: BodyInit | null | undefined;\n} {\n  const headers = new Headers(options.headers);\n\n  let body: BodyInit | null | undefined = options.body;\n\n  if (body == null && options.json !== undefined) {\n    body = JSON.stringify(options.json);\n    if (!headers.has(\"content-type\")) {\n      headers.set(\"content-type\", \"application/json\");\n    }\n  } else if (options.contentType) {\n    headers.set(\"content-type\", options.contentType);\n  }\n\n  const hasBody = body != null;\n  if (hasBody && !headers.has(\"content-type\")) {\n    throw new QueryError(\n      \"A QUERY request with a body must set a Content-Type (RFC 10008). Pass `contentType`, use `json`, or set the header explicitly.\",\n    );\n  }\n\n  if (options.accept !== undefined) {\n    const accept = Array.isArray(options.accept)\n      ? options.accept.join(\", \")\n      : options.accept;\n    headers.set(\"accept\", accept);\n  }\n\n  return { headers, body };\n}\n\n/**\n * Perform an HTTP QUERY request (RFC 10008).\n *\n * QUERY is safe and idempotent like GET, but carries a request body like POST,\n * making it ideal for large or structured queries that don't fit in a URL.\n *\n * Redirects — including the RFC's `303 See Other` indirect-result pattern — are\n * handled by the underlying `fetch` per the request's `redirect` mode (default\n * `\"follow\"`), so no special handling is needed here.\n *\n * @example\n * ```ts\n * const res = await query(\"https://api.example.com/search\", {\n *   json: { filter: { status: \"active\" }, sort: \"-createdAt\" },\n *   accept: \"application/json\",\n * });\n * ```\n */\nexport async function query(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<Response> {\n  const doFetch = resolveFetch(options.fetch);\n  const { headers, body } = prepare(options);\n\n  const {\n    fetch: _fetch,\n    json: _json,\n    contentType: _contentType,\n    accept: _accept,\n    fallbackToPost = true,\n    methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,\n    headers: _headers,\n    body: _body,\n    ...init\n  } = options;\n\n  const response = await doFetch(input, {\n    ...init,\n    method: \"QUERY\",\n    headers,\n    body,\n  });\n\n  if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {\n    return response;\n  }\n\n  // The server doesn't speak QUERY — retry as POST, optionally advertising the\n  // original method so override-aware servers can still treat it as a query.\n  const fallbackHeaders = new Headers(headers);\n  if (methodOverrideHeader) {\n    fallbackHeaders.set(methodOverrideHeader, \"QUERY\");\n  }\n\n  return doFetch(input, {\n    ...init,\n    method: \"POST\",\n    headers: fallbackHeaders,\n    body,\n  });\n}\n\n/**\n * Like {@link query}, but parses the response body as JSON.\n *\n * Throws {@link QueryError} on a non-2xx response so callers don't silently\n * parse an error page.\n */\nexport async function queryJson<T = unknown>(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<QueryJsonResult<T>> {\n  const response = await query(input, {\n    accept: \"application/json\",\n    ...options,\n  });\n\n  if (!response.ok) {\n    throw new QueryError(\n      `QUERY ${input.toString()} failed with status ${response.status} ${response.statusText}`,\n    );\n  }\n\n  return { data: (await response.json()) as T, response };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @danmat/query-fetch\n *\n * A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the\n * safe, idempotent request that carries a body like POST but caches like GET.\n *\n * @see https://www.rfc-editor.org/rfc/rfc10008\n */\n\n/** Status codes that signal a server does not understand the QUERY method. */\nconst METHOD_UNSUPPORTED_STATUSES = new Set([405, 501]);\n\n/** Statuses worth retrying for an idempotent request. */\nconst RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);\n\n/** Default header used to tunnel the intended method when falling back to POST. */\nconst DEFAULT_OVERRIDE_HEADER = \"X-HTTP-Method-Override\";\n\n/**\n * Error thrown when a QUERY request cannot be constructed according to the\n * requirements of RFC 10008 (e.g. a body with no `Content-Type`).\n */\nexport class QueryError extends Error {\n  override name = \"QueryError\";\n\n  constructor(message: string) {\n    super(message);\n    // Restore prototype chain for transpiled/ES5 targets.\n    Object.setPrototypeOf(this, QueryError.prototype);\n  }\n}\n\n/** Details about a failed attempt, passed to retry callbacks. */\nexport interface RetryContext {\n  /** 1-based number of the retry about to happen (or being decided). */\n  attempt: number;\n  /** The response received, when the failure was an HTTP status. */\n  response?: Response;\n  /** The error thrown, when the failure was a network/abort error. */\n  error?: unknown;\n}\n\n/** Controls automatic retries. See {@link QueryOptions.retry}. */\nexport interface RetryOptions {\n  /** Maximum number of retries after the initial attempt. */\n  retries: number;\n  /** Base backoff delay in milliseconds. Default `200`. */\n  minDelay?: number;\n  /** Maximum backoff delay in milliseconds. Default `10000`. */\n  maxDelay?: number;\n  /** Exponential backoff multiplier. Default `2`. */\n  factor?: number;\n  /** Apply random jitter to spread retries out. Default `true`. */\n  jitter?: boolean;\n  /** Honor a `Retry-After` response header (e.g. on 429/503). Default `true`. */\n  respectRetryAfter?: boolean;\n  /**\n   * Decide whether a failed attempt should be retried. By default, network\n   * errors and the statuses 408/425/429/500/502/503/504 are retried, while\n   * aborts are not. QUERY is idempotent, so retrying is safe.\n   */\n  retryOn?: (context: RetryContext) => boolean | Promise<boolean>;\n  /** Called before each backoff wait, with the chosen delay. */\n  onRetry?: (context: RetryContext & { delay: number }) => void;\n}\n\n/** Options for {@link query}. Extends `RequestInit` minus the fields we own. */\nexport interface QueryOptions extends Omit<RequestInit, \"method\" | \"body\"> {\n  /**\n   * The raw query body. Pair with {@link QueryOptions.contentType}. For JSON\n   * payloads prefer {@link QueryOptions.json}, which sets the content type for\n   * you.\n   */\n  body?: BodyInit | null;\n\n  /**\n   * Convenience: a value serialized to JSON and sent as\n   * `application/json`. Ignored if {@link QueryOptions.body} is set.\n   */\n  json?: unknown;\n\n  /**\n   * MIME type of the query body. **Required** whenever a body is present —\n   * RFC 10008 mandates that servers reject a QUERY with a missing or\n   * inconsistent `Content-Type`. Ignored when using {@link QueryOptions.json}.\n   */\n  contentType?: string;\n\n  /** Media type(s) acceptable in the response. Sets the `Accept` header. */\n  accept?: string | string[];\n\n  /**\n   * Retry as `POST` when the server reports it does not support QUERY\n   * (HTTP 405 or 501). Defaults to `true`.\n   */\n  fallbackToPost?: boolean;\n\n  /**\n   * Header name used to advertise the original method on a POST fallback so\n   * that override-aware servers can still route it as a QUERY. Set to `false`\n   * to disable. Defaults to `\"X-HTTP-Method-Override\"`.\n   */\n  methodOverrideHeader?: string | false;\n\n  /**\n   * How to reach a server that may not support QUERY.\n   *\n   * - `\"query\"` (default): send a real QUERY, and — when {@link fallbackToPost}\n   *   is on — fall back to POST only if the server *answers* `405`/`501`.\n   * - `\"post-override\"`: skip QUERY entirely and send POST from the start, with\n   *   the intended method advertised via {@link methodOverrideHeader}. Use this\n   *   for an origin you already know rejects QUERY *before* a clean status comes\n   *   back — a legacy proxy, or a cross-origin server whose CORS allows POST but\n   *   not QUERY yet — where a real QUERY would only fail after a wasted round\n   *   trip (or a CORS preflight the client can't see). This is a deliberate\n   *   opt-in: the request goes out as a POST, so intermediaries treat it as\n   *   unsafe and uncacheable unless the server honors the override. The library\n   *   never switches to this on its own — you decide, per call.\n   */\n  transport?: \"query\" | \"post-override\";\n\n  /**\n   * Automatically retry transient failures. Pass a number for \"retry N times\n   * with sensible backoff\", or a {@link RetryOptions} object for full control.\n   * Because QUERY is idempotent, retrying is safe — unlike POST. Off unless set.\n   *\n   * Retries reuse a buffered body (a string, bytes, or `json`); a streaming\n   * body can only be sent once and won't be retried.\n   */\n  retry?: number | RetryOptions;\n\n  /**\n   * A `fetch` implementation to use instead of the global. Handy for testing\n   * or for runtimes that expose `fetch` on a client rather than globally.\n   */\n  fetch?: typeof fetch;\n}\n\n/** The result of {@link queryJson}: a parsed body plus the originating response. */\nexport interface QueryJsonResult<T> {\n  data: T;\n  response: Response;\n}\n\ninterface ResolvedRetry {\n  retries: number;\n  minDelay: number;\n  maxDelay: number;\n  factor: number;\n  jitter: boolean;\n  respectRetryAfter: boolean;\n  retryOn: (context: RetryContext) => boolean | Promise<boolean>;\n  onRetry?: (context: RetryContext & { delay: number }) => void;\n}\n\nfunction resolveFetch(custom?: typeof fetch): typeof fetch {\n  const impl = custom ?? globalThis.fetch;\n  if (typeof impl !== \"function\") {\n    throw new QueryError(\n      \"No fetch implementation found. Pass `fetch` in options or run on a runtime that provides a global fetch.\",\n    );\n  }\n  return impl;\n}\n\n/**\n * Build the request body and headers, enforcing RFC 10008's `Content-Type`\n * requirement. Returns the effective body so it can be reused by a fallback.\n */\nfunction prepare(options: QueryOptions): {\n  headers: Headers;\n  body: BodyInit | null | undefined;\n} {\n  const headers = new Headers(options.headers);\n\n  let body: BodyInit | null | undefined = options.body;\n\n  if (body == null && options.json !== undefined) {\n    body = JSON.stringify(options.json);\n    if (!headers.has(\"content-type\")) {\n      headers.set(\"content-type\", \"application/json\");\n    }\n  } else if (options.contentType) {\n    headers.set(\"content-type\", options.contentType);\n  }\n\n  const hasBody = body != null;\n  if (hasBody && !headers.has(\"content-type\")) {\n    throw new QueryError(\n      \"A QUERY request with a body must set a Content-Type (RFC 10008). Pass `contentType`, use `json`, or set the header explicitly.\",\n    );\n  }\n\n  if (options.accept !== undefined) {\n    const accept = Array.isArray(options.accept)\n      ? options.accept.join(\", \")\n      : options.accept;\n    headers.set(\"accept\", accept);\n  }\n\n  return { headers, body };\n}\n\nfunction isAbortError(error: unknown): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    (error as { name?: string }).name === \"AbortError\"\n  );\n}\n\nfunction defaultRetryOn(context: RetryContext): boolean {\n  if (context.error !== undefined) return !isAbortError(context.error);\n  if (context.response) return RETRYABLE_STATUSES.has(context.response.status);\n  return false;\n}\n\nfunction resolveRetry(\n  retry: number | RetryOptions | undefined,\n): ResolvedRetry | null {\n  if (retry === undefined) return null;\n  const opts = typeof retry === \"number\" ? { retries: retry } : retry;\n  if (!opts.retries || opts.retries < 1) return null;\n  return {\n    retries: opts.retries,\n    minDelay: opts.minDelay ?? 200,\n    maxDelay: opts.maxDelay ?? 10_000,\n    factor: opts.factor ?? 2,\n    jitter: opts.jitter ?? true,\n    respectRetryAfter: opts.respectRetryAfter ?? true,\n    retryOn: opts.retryOn ?? defaultRetryOn,\n    onRetry: opts.onRetry,\n  };\n}\n\nfunction parseRetryAfter(value: string | null): number | null {\n  if (!value) return null;\n  const seconds = Number(value);\n  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);\n  const date = Date.parse(value);\n  if (Number.isNaN(date)) return null;\n  return Math.max(0, date - Date.now());\n}\n\nfunction backoffDelay(\n  cfg: ResolvedRetry,\n  attemptIndex: number,\n  response?: Response,\n): number {\n  if (cfg.respectRetryAfter && response) {\n    const retryAfter = parseRetryAfter(response.headers.get(\"retry-after\"));\n    if (retryAfter !== null) return retryAfter;\n  }\n  const base = Math.min(\n    cfg.maxDelay,\n    cfg.minDelay * cfg.factor ** attemptIndex,\n  );\n  return cfg.jitter ? base / 2 + Math.random() * (base / 2) : base;\n}\n\nfunction abortError(): Error {\n  const error = new Error(\"The operation was aborted.\");\n  error.name = \"AbortError\";\n  return error;\n}\n\nfunction sleep(ms: number, signal?: AbortSignal | null): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(abortError());\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\n      \"abort\",\n      () => {\n        clearTimeout(timer);\n        reject(abortError());\n      },\n      { once: true },\n    );\n  });\n}\n\n/**\n * Perform an HTTP QUERY request (RFC 10008).\n *\n * QUERY is safe and idempotent like GET, but carries a request body like POST,\n * making it ideal for large or structured queries that don't fit in a URL.\n *\n * Redirects — including the RFC's `303 See Other` indirect-result pattern — are\n * handled by the underlying `fetch` per the request's `redirect` mode (default\n * `\"follow\"`), so no special handling is needed here.\n *\n * @example\n * ```ts\n * const res = await query(\"https://api.example.com/search\", {\n *   json: { filter: { status: \"active\" }, sort: \"-createdAt\" },\n *   accept: \"application/json\",\n *   retry: 3, // safe: QUERY is idempotent\n * });\n * ```\n */\nexport async function query(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<Response> {\n  const doFetch = resolveFetch(options.fetch);\n  const { headers, body } = prepare(options);\n\n  const {\n    fetch: _fetch,\n    json: _json,\n    contentType: _contentType,\n    accept: _accept,\n    retry: _retry,\n    fallbackToPost = true,\n    methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,\n    transport = \"query\",\n    headers: _headers,\n    body: _body,\n    ...init\n  } = options;\n\n  // POST carrying the original method in an override header, for a server that\n  // doesn't speak QUERY. Shared by the explicit `transport: \"post-override\"`\n  // mode and the automatic 405/501 fallback below.\n  const postOverride = (): Promise<Response> => {\n    const overrideHeaders = new Headers(headers);\n    if (methodOverrideHeader) {\n      overrideHeaders.set(methodOverrideHeader, \"QUERY\");\n    }\n    return doFetch(input, {\n      ...init,\n      method: \"POST\",\n      headers: overrideHeaders,\n      body,\n    });\n  };\n\n  const attempt = async (): Promise<Response> => {\n    // Caller already knows this origin won't accept a QUERY: don't waste the\n    // round trip, POST with the override from the start.\n    if (transport === \"post-override\") return postOverride();\n\n    const response = await doFetch(input, {\n      ...init,\n      method: \"QUERY\",\n      headers,\n      body,\n    });\n\n    // The server *answered* that it doesn't speak QUERY — fall back to POST,\n    // advertising the original method so override-aware servers still treat it\n    // as one. Only fires on an explicit 405/501, never on an opaque throw.\n    if (!fallbackToPost || !METHOD_UNSUPPORTED_STATUSES.has(response.status)) {\n      return response;\n    }\n    return postOverride();\n  };\n\n  const retryCfg = resolveRetry(options.retry);\n  if (!retryCfg) return attempt();\n\n  const signal = init.signal ?? null;\n  for (let i = 0; ; i++) {\n    let response: Response | undefined;\n    let caught: unknown;\n    try {\n      response = await attempt();\n    } catch (error) {\n      caught = error;\n    }\n\n    const isLastAttempt = i >= retryCfg.retries;\n    const context: RetryContext = { attempt: i + 1, response, error: caught };\n\n    if (caught !== undefined) {\n      if (\n        isLastAttempt ||\n        isAbortError(caught) ||\n        !(await retryCfg.retryOn(context))\n      ) {\n        throw caught;\n      }\n    } else if (isLastAttempt || !(await retryCfg.retryOn(context))) {\n      return response as Response;\n    }\n\n    const delay = backoffDelay(retryCfg, i, response);\n    retryCfg.onRetry?.({ ...context, delay });\n    await sleep(delay, signal);\n  }\n}\n\n/**\n * Like {@link query}, but parses the response body as JSON.\n *\n * Throws {@link QueryError} on a non-2xx response so callers don't silently\n * parse an error page.\n */\nexport async function queryJson<T = unknown>(\n  input: string | URL,\n  options: QueryOptions = {},\n): Promise<QueryJsonResult<T>> {\n  const response = await query(input, {\n    accept: \"application/json\",\n    ...options,\n  });\n\n  if (!response.ok) {\n    throw new QueryError(\n      `QUERY ${input.toString()} failed with status ${response.status} ${response.statusText}`,\n    );\n  }\n\n  return { data: (await response.json()) as T, response };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmat/query-fetch",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the safe, idempotent request with a body. Content-Type enforcement, POST fallback, and Accept negotiation over native fetch.",
   "keywords": [
     "http",
@@ -12,7 +12,9 @@
     "safe-method",
     "idempotent",
     "search",
-    "api-client"
+    "api-client",
+    "retry",
+    "backoff"
   ],
   "type": "module",
   "main": "./dist/index.cjs",