create-request 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.2.0 — 2026-10-09
+
+### Added
+
+- `create.query()`, `createQuery()`, `api.query()` and the `QueryRequest` type for the HTTP `QUERY` method ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)): a safe, idempotent read whose query is sent in the body, for searches too large or too structured for a URL. `"QUERY"` joins the `Method` and `BodyMethod` unions, so `withBody()` and `withGraphQL()` accept it and `withRetries({ methods })` can list it; a `switch` that handles every `Method` needs a `"QUERY"` case.
+
 ## 2.1.0 — 2026-10-03
 
 ### Added

package/README.md

@@ -104,15 +104,26 @@ try {
 ### Creating
 
 ```typescript
-create.get(url); // also head, options, post, put, patch, delete (alias: del)
+create.get(url); // also head, options, post, put, patch, delete (alias: del), query
 api.get("/users"); // joined to the api's base URL
 api.get(); // no path → the base URL itself
 api.get<User>("/me"); // declare the JSON type once; getJson() / getData() / getResult() use it
 ```
 
 Named factories exist as well: `createGet`, `createPost`, `createPut`, `createPatch`,
-`createDelete`, `createHead`, `createOptions` (the same functions as `create.get`, …), and
-`createApi()` is also available as `create.api()`.
+`createDelete`, `createHead`, `createOptions`, `createQuery` (the same functions as
+`create.get`, …), and `createApi()` is also available as `create.api()`.
+
+`QUERY` works like `GET`, but the query goes in the body:
+
+```typescript
+const results = await api
+  .query<Page<Post>>("/posts/search")
+  .withBody({ text: "fetch", tags: ["http"], sort: "recent" })
+  .getJson();
+```
+
+The server must support `QUERY`. In browsers, a cross-origin `QUERY` request is preflighted.
 
 ### Configuring
 
@@ -129,7 +140,7 @@ create
   // and a key set twice keeps the last value (a request can override an api default)
   .withQueryParams({ page: 2, tags: ["a", "b"], since: new Date() })
   .withQueryParam("q", "search term")
-  // body (POST, PUT, PATCH, DELETE only): objects → JSON, strings → text/plain,
+  // body (POST, PUT, PATCH, DELETE, QUERY only): objects → JSON, strings → text/plain,
   // FormData / Blob / URLSearchParams / ArrayBuffer / typed arrays / ReadableStream → sent as-is
   .withBody({ name: "Ada" })
   // resilience
@@ -296,7 +307,7 @@ api.get("/status").withRetries({
   attempts: 3,
   delay: ({ attempt }) => attempt * 500, // ms, or a number; default: exponential backoff
   statuses: [503], // default: 408, 425, 429, 500, 502, 503, 504
-  methods: ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"], // default: all, POST and PATCH included
+  methods: ["GET", "HEAD", "OPTIONS", "QUERY", "PUT", "DELETE"], // default: all, POST and PATCH included
   maxDelay: 10_000, // caps the backoff (default 30 s); a longer Retry-After gives up instead
   shouldRetry: ({ error }) => error.code === "NETWORK", // full override of the decision
   onRetry: ({ attempt, error, delay }) =>
@@ -310,8 +321,8 @@ How retries behave:
   backoff (300 ms, 600 ms, 1.2 s, … plus up to 100 ms of jitter, capped at `maxDelay`);
   validation errors and other failures are not.
 - Every method is retried by default, `POST` and `PATCH` included. Pass
-  `methods: ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]` if a repeated request could duplicate
-  work.
+  `methods: ["GET", "HEAD", "OPTIONS", "QUERY", "PUT", "DELETE"]` if a repeated request could
+  duplicate work.
 - A `Retry-After` header is honoured unless you set `delay`; one longer than `maxDelay` cancels
   the retry so you can react yourself.
 - Aborted requests and requests with a stream body are never retried, whatever the policy. That
@@ -531,7 +542,7 @@ Measured with `size-limit` on the published build of this version (`npm run size
 
 | Import                         | min + gzip | min + brotli |
 | ------------------------------ | ---------: | -----------: |
-| everything (`import * as …`)   |    4.92 KB |      4.46 KB |
+| everything (`import * as …`)   |    4.95 KB |      4.48 KB |
 | `import { createGet }` only    |    4.32 KB |              |
 | `import { RequestError }` only |    0.25 KB |              |
 

package/dist/index.cjs

@@ -685,7 +685,8 @@ const METHODS = [
 	"POST",
 	"PUT",
 	"PATCH",
-	"DELETE"
+	"DELETE",
+	"QUERY"
 ];
 let installed = false;
 function createApi() {
@@ -712,6 +713,7 @@ const createPost = (url) => new HttpRequest("POST", url);
 const createPut = (url) => new HttpRequest("PUT", url);
 const createPatch = (url) => new HttpRequest("PATCH", url);
 const createDelete = (url) => new HttpRequest("DELETE", url);
+const createQuery = (url) => new HttpRequest("QUERY", url);
 const create = {
 	get: createGet,
 	head: createHead,
@@ -721,6 +723,7 @@ const create = {
 	patch: createPatch,
 	delete: createDelete,
 	del: createDelete,
+	query: createQuery,
 	api: createApi
 };
 
@@ -736,5 +739,6 @@ exports.createOptions = createOptions;
 exports.createPatch = createPatch;
 exports.createPost = createPost;
 exports.createPut = createPut;
+exports.createQuery = createQuery;
 exports.default = create;
 exports.isRequestError = isRequestError;

package/dist/index.d.cts

@@ -163,10 +163,13 @@ export declare class RequestError<TData = unknown> extends Error {
 export declare const isRequestError: (error: unknown) => error is RequestError;
 //#endregion
 //#region src/types.d.ts
-/** The HTTP methods a request can be created with. */
-type Method = "GET" | "HEAD" | "OPTIONS" | "DELETE" | "POST" | "PUT" | "PATCH";
+/**
+ * The HTTP methods a request can be created with. `QUERY` ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)) is a
+ * safe, idempotent read like `GET` whose query is sent in the body.
+ */
+type Method = "GET" | "HEAD" | "OPTIONS" | "DELETE" | "POST" | "PUT" | "PATCH" | "QUERY";
 /** The HTTP methods that may carry a request body (`withBody` / `withGraphQL` are only available on these). */
-type BodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+type BodyMethod = "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
 /** What `fetch` accepts as a body. */
 type FetchBody = NonNullable<RequestInit["body"]>;
 /** `"include"`, `"omit"` or `"same-origin"`. */
@@ -261,7 +264,7 @@ interface RetryConfig {
   delay?: number | ((context: RetryContext) => number) | undefined;
   /** Statuses that are retried. Default: `[408, 425, 429, 500, 502, 503, 504]`. Network errors and timeouts are retried by default. */
   statuses?: readonly number[] | undefined;
-  /** Methods that are retried. Default: all. Use `["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]` to retry idempotent requests only. */
+  /** Methods that are retried. Default: all. Use `["GET", "HEAD", "OPTIONS", "QUERY", "PUT", "DELETE"]` to retry idempotent requests only. */
   methods?: readonly Method[] | undefined;
   /**
    * Upper bound, in milliseconds, for the default backoff. A `Retry-After` header longer than this
@@ -651,7 +654,7 @@ export declare class HttpRequest<M extends Method = Method, T = unknown> {
   /** Adds an {@link ErrorInterceptor}, run once after the request has failed for good (after retries); it also receives the request, so it can replay it. */
   withErrorInterceptor(interceptor: ErrorInterceptor): this;
   /**
-   * Sets the request body (POST, PUT, PATCH and DELETE only — a compile error elsewhere). Objects and
+   * Sets the request body (POST, PUT, PATCH, DELETE and QUERY only — a compile error elsewhere). Objects and
    * arrays are JSON-encoded; strings, `Blob`, `FormData`, `URLSearchParams`, `ArrayBuffer`, typed arrays
    * and `ReadableStream` are sent as-is. `Content-Type` is set to `application/json` / `text/plain`
    * unless already present, and removed for `FormData` (fetch must add the multipart boundary itself).
@@ -799,6 +802,8 @@ interface ApiBuilder extends ApiChainables {
   delete<T = unknown>(path?: string): HttpRequest<"DELETE", T>;
   /** Alias of `delete`. */
   del<T = unknown>(path?: string): HttpRequest<"DELETE", T>;
+  /** Creates a QUERY request (RFC 10008): a safe, idempotent read whose query is sent with `withBody()`. */
+  query<T = unknown>(path?: string): HttpRequest<"QUERY", T>;
 }
 /**
  * Creates an empty {@link ApiBuilder}. Configure it once, export it, and create every request through it.
@@ -821,9 +826,11 @@ export type PutRequest<T = unknown> = HttpRequest<"PUT", T>;
 export type PatchRequest<T = unknown> = HttpRequest<"PATCH", T>;
 /** A DELETE request. */
 export type DeleteRequest<T = unknown> = HttpRequest<"DELETE", T>;
+/** A QUERY request (RFC 10008). */
+export type QueryRequest<T = unknown> = HttpRequest<"QUERY", T>;
 /** Any request — the v1 name for {@link HttpRequest}. */
 export type BaseRequest<T = unknown> = HttpRequest<Method, T>;
-/** Any request that may carry a body — the v1 name for `HttpRequest<"POST" | "PUT" | "PATCH" | "DELETE">`. */
+/** Any request that may carry a body — the v1 name for `HttpRequest<"POST" | "PUT" | "PATCH" | "DELETE" | "QUERY">`. */
 export type BodyRequest<T = unknown> = HttpRequest<BodyMethod, T>;
 /** Creates a GET request. `T` declares the JSON type the response is expected to have. */
 export declare const createGet: <T = unknown>(url: string) => GetRequest<T>;
@@ -839,6 +846,17 @@ export declare const createPut: <T = unknown>(url: string) => PutRequest<T>;
 export declare const createPatch: <T = unknown>(url: string) => PatchRequest<T>;
 /** Creates a DELETE request. */
 export declare const createDelete: <T = unknown>(url: string) => DeleteRequest<T>;
+/**
+ * Creates a QUERY request ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)): a safe, idempotent read like GET
+ * whose query travels in the body, so it can be as large and as structured as needed. The server must support the
+ * method and needs a `Content-Type`, which is set for you except for binary and stream bodies (use `withContentType()`).
+ *
+ * @example
+ * ```typescript
+ * const open = await create.query<Issue[]>("https://api.example.com/issues").withBody({ state: "open", labels: ["bug"] }).getJson();
+ * ```
+ */
+export declare const createQuery: <T = unknown>(url: string) => QueryRequest<T>;
 /**
  * The entry point: one factory per HTTP method plus `api()` for configured instances.
  *
@@ -868,6 +886,8 @@ declare const create: {
   readonly delete: <T = unknown>(url: string) => DeleteRequest<T>;
   /** Alias of `delete`. */
   readonly del: <T = unknown>(url: string) => DeleteRequest<T>;
+  /** Creates a QUERY request (RFC 10008): a safe, idempotent read whose query is sent with `withBody()` — see {@link createQuery}. */
+  readonly query: <T = unknown>(url: string) => QueryRequest<T>;
   /** Creates an api instance — see {@link createApi}. */
   readonly api: typeof createApi;
 };

package/dist/index.d.ts

@@ -163,10 +163,13 @@ export declare class RequestError<TData = unknown> extends Error {
 export declare const isRequestError: (error: unknown) => error is RequestError;
 //#endregion
 //#region src/types.d.ts
-/** The HTTP methods a request can be created with. */
-type Method = "GET" | "HEAD" | "OPTIONS" | "DELETE" | "POST" | "PUT" | "PATCH";
+/**
+ * The HTTP methods a request can be created with. `QUERY` ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)) is a
+ * safe, idempotent read like `GET` whose query is sent in the body.
+ */
+type Method = "GET" | "HEAD" | "OPTIONS" | "DELETE" | "POST" | "PUT" | "PATCH" | "QUERY";
 /** The HTTP methods that may carry a request body (`withBody` / `withGraphQL` are only available on these). */
-type BodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+type BodyMethod = "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
 /** What `fetch` accepts as a body. */
 type FetchBody = NonNullable<RequestInit["body"]>;
 /** `"include"`, `"omit"` or `"same-origin"`. */
@@ -261,7 +264,7 @@ interface RetryConfig {
   delay?: number | ((context: RetryContext) => number) | undefined;
   /** Statuses that are retried. Default: `[408, 425, 429, 500, 502, 503, 504]`. Network errors and timeouts are retried by default. */
   statuses?: readonly number[] | undefined;
-  /** Methods that are retried. Default: all. Use `["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]` to retry idempotent requests only. */
+  /** Methods that are retried. Default: all. Use `["GET", "HEAD", "OPTIONS", "QUERY", "PUT", "DELETE"]` to retry idempotent requests only. */
   methods?: readonly Method[] | undefined;
   /**
    * Upper bound, in milliseconds, for the default backoff. A `Retry-After` header longer than this
@@ -651,7 +654,7 @@ export declare class HttpRequest<M extends Method = Method, T = unknown> {
   /** Adds an {@link ErrorInterceptor}, run once after the request has failed for good (after retries); it also receives the request, so it can replay it. */
   withErrorInterceptor(interceptor: ErrorInterceptor): this;
   /**
-   * Sets the request body (POST, PUT, PATCH and DELETE only — a compile error elsewhere). Objects and
+   * Sets the request body (POST, PUT, PATCH, DELETE and QUERY only — a compile error elsewhere). Objects and
    * arrays are JSON-encoded; strings, `Blob`, `FormData`, `URLSearchParams`, `ArrayBuffer`, typed arrays
    * and `ReadableStream` are sent as-is. `Content-Type` is set to `application/json` / `text/plain`
    * unless already present, and removed for `FormData` (fetch must add the multipart boundary itself).
@@ -799,6 +802,8 @@ interface ApiBuilder extends ApiChainables {
   delete<T = unknown>(path?: string): HttpRequest<"DELETE", T>;
   /** Alias of `delete`. */
   del<T = unknown>(path?: string): HttpRequest<"DELETE", T>;
+  /** Creates a QUERY request (RFC 10008): a safe, idempotent read whose query is sent with `withBody()`. */
+  query<T = unknown>(path?: string): HttpRequest<"QUERY", T>;
 }
 /**
  * Creates an empty {@link ApiBuilder}. Configure it once, export it, and create every request through it.
@@ -821,9 +826,11 @@ export type PutRequest<T = unknown> = HttpRequest<"PUT", T>;
 export type PatchRequest<T = unknown> = HttpRequest<"PATCH", T>;
 /** A DELETE request. */
 export type DeleteRequest<T = unknown> = HttpRequest<"DELETE", T>;
+/** A QUERY request (RFC 10008). */
+export type QueryRequest<T = unknown> = HttpRequest<"QUERY", T>;
 /** Any request — the v1 name for {@link HttpRequest}. */
 export type BaseRequest<T = unknown> = HttpRequest<Method, T>;
-/** Any request that may carry a body — the v1 name for `HttpRequest<"POST" | "PUT" | "PATCH" | "DELETE">`. */
+/** Any request that may carry a body — the v1 name for `HttpRequest<"POST" | "PUT" | "PATCH" | "DELETE" | "QUERY">`. */
 export type BodyRequest<T = unknown> = HttpRequest<BodyMethod, T>;
 /** Creates a GET request. `T` declares the JSON type the response is expected to have. */
 export declare const createGet: <T = unknown>(url: string) => GetRequest<T>;
@@ -839,6 +846,17 @@ export declare const createPut: <T = unknown>(url: string) => PutRequest<T>;
 export declare const createPatch: <T = unknown>(url: string) => PatchRequest<T>;
 /** Creates a DELETE request. */
 export declare const createDelete: <T = unknown>(url: string) => DeleteRequest<T>;
+/**
+ * Creates a QUERY request ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)): a safe, idempotent read like GET
+ * whose query travels in the body, so it can be as large and as structured as needed. The server must support the
+ * method and needs a `Content-Type`, which is set for you except for binary and stream bodies (use `withContentType()`).
+ *
+ * @example
+ * ```typescript
+ * const open = await create.query<Issue[]>("https://api.example.com/issues").withBody({ state: "open", labels: ["bug"] }).getJson();
+ * ```
+ */
+export declare const createQuery: <T = unknown>(url: string) => QueryRequest<T>;
 /**
  * The entry point: one factory per HTTP method plus `api()` for configured instances.
  *
@@ -868,6 +886,8 @@ declare const create: {
   readonly delete: <T = unknown>(url: string) => DeleteRequest<T>;
   /** Alias of `delete`. */
   readonly del: <T = unknown>(url: string) => DeleteRequest<T>;
+  /** Creates a QUERY request (RFC 10008): a safe, idempotent read whose query is sent with `withBody()` — see {@link createQuery}. */
+  readonly query: <T = unknown>(url: string) => QueryRequest<T>;
   /** Creates an api instance — see {@link createApi}. */
   readonly api: typeof createApi;
 };

package/dist/index.js

@@ -684,7 +684,8 @@ const METHODS = [
 	"POST",
 	"PUT",
 	"PATCH",
-	"DELETE"
+	"DELETE",
+	"QUERY"
 ];
 let installed = false;
 function createApi() {
@@ -711,6 +712,7 @@ const createPost = (url) => new HttpRequest("POST", url);
 const createPut = (url) => new HttpRequest("PUT", url);
 const createPatch = (url) => new HttpRequest("PATCH", url);
 const createDelete = (url) => new HttpRequest("DELETE", url);
+const createQuery = (url) => new HttpRequest("QUERY", url);
 const create = {
 	get: createGet,
 	head: createHead,
@@ -720,8 +722,9 @@ const create = {
 	patch: createPatch,
 	delete: createDelete,
 	del: createDelete,
+	query: createQuery,
 	api: createApi
 };
 
 //#endregion
-export { HttpRequest, RequestError, ResponseWrapper, createApi, createDelete, createGet, createHead, createOptions, createPatch, createPost, createPut, create as default, isRequestError };
+export { HttpRequest, RequestError, ResponseWrapper, createApi, createDelete, createGet, createHead, createOptions, createPatch, createPost, createPut, createQuery, create as default, isRequestError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-request",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A tiny, chainable, fully typed wrapper around fetch: retries, timeouts, cancellation, interceptors, api instances, schema validation and one error type",
   "type": "module",
   "sideEffects": false,