@danmat/query-fetch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Matthew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @danmat/query-fetch
+
+[![CI](https://github.com/DanMat/query-fetch/actions/workflows/ci.yml/badge.svg)](https://github.com/DanMat/query-fetch/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@danmat/query-fetch.svg)](https://www.npmjs.com/package/@danmat/query-fetch)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@danmat/query-fetch)](https://bundlephobia.com/package/@danmat/query-fetch)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+A tiny, **dependency-free** client for the HTTP **QUERY** method ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)) — the request that is *safe and idempotent like `GET`*, but *carries a body like `POST`*, and *caches like neither before it could*.
+
+Built on native `fetch`. Works in Node 18+, Deno, Bun, Cloudflare Workers, and the browser.
+
+```ts
+import { query } from "@danmat/query-fetch";
+
+const res = await query("https://api.example.com/search", {
+  json: { filter: { status: "active" }, sort: "-createdAt", limit: 50 },
+});
+```
+
+## Why QUERY?
+
+For years you had two bad options for a search endpoint:
+
+- **`GET` with a query string** — safe, idempotent, cacheable… but your filter blows past URL length limits and leaks into logs.
+- **`POST` with a body** — room for a rich query… but it's neither safe, idempotent, nor cacheable, so proxies and clients treat it as a state change.
+
+`QUERY` is the missing third option: a body-carrying request that intermediaries may cache and clients may safely retry. This library handles the sharp edges the spec introduces.
+
+## Install
+
+```sh
+npm install @danmat/query-fetch
+```
+
+## What it does for you
+
+Scripted `fetch(url, { method: "QUERY", body })` already works in modern runtimes — but the *semantics* of RFC 10008 are on you. This library covers them:
+
+- ✅ **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.
+- ✅ **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.
+
+## Usage
+
+### JSON queries
+
+```ts
+import { queryJson } from "@danmat/query-fetch";
+
+const { data, response } = await queryJson<{ total: number }>(
+  "https://api.example.com/search",
+  { json: { q: "http query method" } },
+);
+
+console.log(data.total, response.headers.get("age"));
+```
+
+`queryJson` sets `Accept: application/json`, throws on a non-2xx status, and returns the parsed body alongside the raw `Response`.
+
+### Raw bodies with an explicit content type
+
+```ts
+await query("https://api.example.com/search", {
+  body: "SELECT * WHERE status = 'active'",
+  contentType: "application/sql",
+  accept: "application/json",
+});
+```
+
+### Opt out of the POST fallback
+
+```ts
+await query(url, { json, fallbackToPost: false });
+```
+
+### Bring your own `fetch`
+
+```ts
+import { fetch as undiciFetch } from "undici";
+
+await query(url, { json, fetch: undiciFetch });
+```
+
+## API
+
+### `query(input, options?): Promise<Response>`
+
+Performs a QUERY request. `options` extends `RequestInit` (so `signal`, `credentials`, `redirect`, etc. all work), minus `method` and with a richer `body`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `body` | `BodyInit \| null` | — | Raw query body. Pair with `contentType`. |
+| `json` | `unknown` | — | Value serialized to JSON; sets `application/json`. |
+| `contentType` | `string` | — | MIME type of `body`. Required when a body is present. |
+| `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. |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation. |
+
+### `queryJson<T>(input, options?): Promise<{ data: T; response: Response }>`
+
+`query` + JSON parsing + a non-2xx guard.
+
+### `QueryError`
+
+Thrown for construction-time problems (a body without a content type, no available `fetch`) and non-2xx responses in `queryJson`.
+
+## Caveats & status
+
+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.
+- **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.
+
+## License
+
+[MIT](./LICENSE) © Dan Matthew

package/dist/index.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+// src/index.ts
+var METHOD_UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([405, 501]);
+var DEFAULT_OVERRIDE_HEADER = "X-HTTP-Method-Override";
+var QueryError = class _QueryError extends Error {
+  name = "QueryError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, _QueryError.prototype);
+  }
+};
+function resolveFetch(custom) {
+  const impl = custom ?? globalThis.fetch;
+  if (typeof impl !== "function") {
+    throw new QueryError(
+      "No fetch implementation found. Pass `fetch` in options or run on a runtime that provides a global fetch."
+    );
+  }
+  return impl;
+}
+function prepare(options) {
+  const headers = new Headers(options.headers);
+  let body = options.body;
+  if (body == null && options.json !== void 0) {
+    body = JSON.stringify(options.json);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+  } else if (options.contentType) {
+    headers.set("content-type", options.contentType);
+  }
+  const hasBody = body != null;
+  if (hasBody && !headers.has("content-type")) {
+    throw new QueryError(
+      "A QUERY request with a body must set a Content-Type (RFC 10008). Pass `contentType`, use `json`, or set the header explicitly."
+    );
+  }
+  if (options.accept !== void 0) {
+    const accept = Array.isArray(options.accept) ? options.accept.join(", ") : options.accept;
+    headers.set("accept", accept);
+  }
+  return { headers, body };
+}
+async function query(input, options = {}) {
+  const doFetch = resolveFetch(options.fetch);
+  const { headers, body } = prepare(options);
+  const {
+    fetch: _fetch,
+    json: _json,
+    contentType: _contentType,
+    accept: _accept,
+    fallbackToPost = true,
+    methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,
+    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");
+  }
+  return doFetch(input, {
+    ...init,
+    method: "POST",
+    headers: fallbackHeaders,
+    body
+  });
+}
+async function queryJson(input, options = {}) {
+  const response = await query(input, {
+    accept: "application/json",
+    ...options
+  });
+  if (!response.ok) {
+    throw new QueryError(
+      `QUERY ${input.toString()} failed with status ${response.status} ${response.statusText}`
+    );
+  }
+  return { data: await response.json(), response };
+}
+
+exports.QueryError = QueryError;
+exports.query = query;
+exports.queryJson = queryJson;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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\n  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"]}

package/dist/index.d.cts

@@ -0,0 +1,87 @@
+/**
+ * @danmat/query-fetch
+ *
+ * A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the
+ * safe, idempotent request that carries a body like POST but caches like GET.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc10008
+ */
+/**
+ * Error thrown when a QUERY request cannot be constructed according to the
+ * requirements of RFC 10008 (e.g. a body with no `Content-Type`).
+ */
+declare class QueryError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/** Options for {@link query}. Extends `RequestInit` minus the fields we own. */
+interface QueryOptions extends Omit<RequestInit, "method" | "body"> {
+    /**
+     * The raw query body. Pair with {@link QueryOptions.contentType}. For JSON
+     * payloads prefer {@link QueryOptions.json}, which sets the content type for
+     * you.
+     */
+    body?: BodyInit | null;
+    /**
+     * Convenience: a value serialized to JSON and sent as
+     * `application/json`. Ignored if {@link QueryOptions.body} is set.
+     */
+    json?: unknown;
+    /**
+     * MIME type of the query body. **Required** whenever a body is present —
+     * RFC 10008 mandates that servers reject a QUERY with a missing or
+     * inconsistent `Content-Type`. Ignored when using {@link QueryOptions.json}.
+     */
+    contentType?: string;
+    /** Media type(s) acceptable in the response. Sets the `Accept` header. */
+    accept?: string | string[];
+    /**
+     * Retry as `POST` when the server reports it does not support QUERY
+     * (HTTP 405 or 501). Defaults to `true`.
+     */
+    fallbackToPost?: boolean;
+    /**
+     * Header name used to advertise the original method on a POST fallback so
+     * that override-aware servers can still route it as a QUERY. Set to `false`
+     * to disable. Defaults to `"X-HTTP-Method-Override"`.
+     */
+    methodOverrideHeader?: string | false;
+    /**
+     * A `fetch` implementation to use instead of the global. Handy for testing
+     * or for runtimes that expose `fetch` on a client rather than globally.
+     */
+    fetch?: typeof fetch;
+}
+/** The result of {@link queryJson}: a parsed body plus the originating response. */
+interface QueryJsonResult<T> {
+    data: T;
+    response: Response;
+}
+/**
+ * Perform an HTTP QUERY request (RFC 10008).
+ *
+ * QUERY is safe and idempotent like GET, but carries a request body like POST,
+ * making it ideal for large or structured queries that don't fit in a URL.
+ *
+ * Redirects — including the RFC's `303 See Other` indirect-result pattern — are
+ * handled by the underlying `fetch` per the request's `redirect` mode (default
+ * `"follow"`), so no special handling is needed here.
+ *
+ * @example
+ * ```ts
+ * const res = await query("https://api.example.com/search", {
+ *   json: { filter: { status: "active" }, sort: "-createdAt" },
+ *   accept: "application/json",
+ * });
+ * ```
+ */
+declare function query(input: string | URL, options?: QueryOptions): Promise<Response>;
+/**
+ * Like {@link query}, but parses the response body as JSON.
+ *
+ * Throws {@link QueryError} on a non-2xx response so callers don't silently
+ * parse an error page.
+ */
+declare function queryJson<T = unknown>(input: string | URL, options?: QueryOptions): Promise<QueryJsonResult<T>>;
+
+export { QueryError, type QueryJsonResult, type QueryOptions, query, queryJson };

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @danmat/query-fetch
+ *
+ * A tiny, dependency-free client for the HTTP QUERY method (RFC 10008) — the
+ * safe, idempotent request that carries a body like POST but caches like GET.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc10008
+ */
+/**
+ * Error thrown when a QUERY request cannot be constructed according to the
+ * requirements of RFC 10008 (e.g. a body with no `Content-Type`).
+ */
+declare class QueryError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/** Options for {@link query}. Extends `RequestInit` minus the fields we own. */
+interface QueryOptions extends Omit<RequestInit, "method" | "body"> {
+    /**
+     * The raw query body. Pair with {@link QueryOptions.contentType}. For JSON
+     * payloads prefer {@link QueryOptions.json}, which sets the content type for
+     * you.
+     */
+    body?: BodyInit | null;
+    /**
+     * Convenience: a value serialized to JSON and sent as
+     * `application/json`. Ignored if {@link QueryOptions.body} is set.
+     */
+    json?: unknown;
+    /**
+     * MIME type of the query body. **Required** whenever a body is present —
+     * RFC 10008 mandates that servers reject a QUERY with a missing or
+     * inconsistent `Content-Type`. Ignored when using {@link QueryOptions.json}.
+     */
+    contentType?: string;
+    /** Media type(s) acceptable in the response. Sets the `Accept` header. */
+    accept?: string | string[];
+    /**
+     * Retry as `POST` when the server reports it does not support QUERY
+     * (HTTP 405 or 501). Defaults to `true`.
+     */
+    fallbackToPost?: boolean;
+    /**
+     * Header name used to advertise the original method on a POST fallback so
+     * that override-aware servers can still route it as a QUERY. Set to `false`
+     * to disable. Defaults to `"X-HTTP-Method-Override"`.
+     */
+    methodOverrideHeader?: string | false;
+    /**
+     * A `fetch` implementation to use instead of the global. Handy for testing
+     * or for runtimes that expose `fetch` on a client rather than globally.
+     */
+    fetch?: typeof fetch;
+}
+/** The result of {@link queryJson}: a parsed body plus the originating response. */
+interface QueryJsonResult<T> {
+    data: T;
+    response: Response;
+}
+/**
+ * Perform an HTTP QUERY request (RFC 10008).
+ *
+ * QUERY is safe and idempotent like GET, but carries a request body like POST,
+ * making it ideal for large or structured queries that don't fit in a URL.
+ *
+ * Redirects — including the RFC's `303 See Other` indirect-result pattern — are
+ * handled by the underlying `fetch` per the request's `redirect` mode (default
+ * `"follow"`), so no special handling is needed here.
+ *
+ * @example
+ * ```ts
+ * const res = await query("https://api.example.com/search", {
+ *   json: { filter: { status: "active" }, sort: "-createdAt" },
+ *   accept: "application/json",
+ * });
+ * ```
+ */
+declare function query(input: string | URL, options?: QueryOptions): Promise<Response>;
+/**
+ * Like {@link query}, but parses the response body as JSON.
+ *
+ * Throws {@link QueryError} on a non-2xx response so callers don't silently
+ * parse an error page.
+ */
+declare function queryJson<T = unknown>(input: string | URL, options?: QueryOptions): Promise<QueryJsonResult<T>>;
+
+export { QueryError, type QueryJsonResult, type QueryOptions, query, queryJson };

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/index.ts
+var METHOD_UNSUPPORTED_STATUSES = /* @__PURE__ */ new Set([405, 501]);
+var DEFAULT_OVERRIDE_HEADER = "X-HTTP-Method-Override";
+var QueryError = class _QueryError extends Error {
+  name = "QueryError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, _QueryError.prototype);
+  }
+};
+function resolveFetch(custom) {
+  const impl = custom ?? globalThis.fetch;
+  if (typeof impl !== "function") {
+    throw new QueryError(
+      "No fetch implementation found. Pass `fetch` in options or run on a runtime that provides a global fetch."
+    );
+  }
+  return impl;
+}
+function prepare(options) {
+  const headers = new Headers(options.headers);
+  let body = options.body;
+  if (body == null && options.json !== void 0) {
+    body = JSON.stringify(options.json);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+  } else if (options.contentType) {
+    headers.set("content-type", options.contentType);
+  }
+  const hasBody = body != null;
+  if (hasBody && !headers.has("content-type")) {
+    throw new QueryError(
+      "A QUERY request with a body must set a Content-Type (RFC 10008). Pass `contentType`, use `json`, or set the header explicitly."
+    );
+  }
+  if (options.accept !== void 0) {
+    const accept = Array.isArray(options.accept) ? options.accept.join(", ") : options.accept;
+    headers.set("accept", accept);
+  }
+  return { headers, body };
+}
+async function query(input, options = {}) {
+  const doFetch = resolveFetch(options.fetch);
+  const { headers, body } = prepare(options);
+  const {
+    fetch: _fetch,
+    json: _json,
+    contentType: _contentType,
+    accept: _accept,
+    fallbackToPost = true,
+    methodOverrideHeader = DEFAULT_OVERRIDE_HEADER,
+    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");
+  }
+  return doFetch(input, {
+    ...init,
+    method: "POST",
+    headers: fallbackHeaders,
+    body
+  });
+}
+async function queryJson(input, options = {}) {
+  const response = await query(input, {
+    accept: "application/json",
+    ...options
+  });
+  if (!response.ok) {
+    throw new QueryError(
+      `QUERY ${input.toString()} failed with status ${response.status} ${response.statusText}`
+    );
+  }
+  return { data: await response.json(), response };
+}
+
+export { QueryError, query, queryJson };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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\n  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"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@danmat/query-fetch",
+  "version": "0.1.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",
+    "query",
+    "query-method",
+    "rfc10008",
+    "rfc-10008",
+    "fetch",
+    "safe-method",
+    "idempotent",
+    "search",
+    "api-client"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Dan Matthew <dannymatthew@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanMat/query-fetch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DanMat/query-fetch/issues"
+  },
+  "homepage": "https://github.com/DanMat/query-fetch#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}