Add QUERY method support

Author: sindresorhus

readme.md

@@ -173,6 +173,7 @@ console.log(bytes instanceof Uint8Array);
 ### ky.patch(input, options?)
 ### ky.head(input, options?)
 ### ky.delete(input, options?)
+### ky.query(input, options?)
 
 Sets `options.method` to the method name and makes a request.
 
@@ -199,7 +200,7 @@ Default: `'get'`
 
 HTTP method used to make the request.
 
-Internally, the standard methods (`GET`, `POST`, `PUT`, `PATCH`, `HEAD` and `DELETE`) are uppercased in order to avoid server errors due to case sensitivity.
+Internally, the standard methods (`GET`, `POST`, `PUT`, `PATCH`, `HEAD`, `DELETE`, and `QUERY`) are uppercased in order to avoid server errors due to case sensitivity.
 
 ##### json
 
@@ -277,7 +278,7 @@ Notes:
 Type: `object | number`\
 Default:
 - `limit`: `2`
-- `methods`: `get` `put` `head` `delete` `options` `trace`
+- `methods`: `get` `put` `head` `delete` `options` `trace` `query`
 - `statusCodes`: [`408`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) [`413`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) [`429`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) [`500`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) [`502`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) [`503`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) [`504`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504)
 - `afterStatusCodes`: [`413`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413), [`429`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429), [`503`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503)
 - `maxRetryAfter`: `Infinity`

source/core/constants.ts

@@ -36,7 +36,7 @@ export const supportsAbortSignal = typeof globalThis.AbortSignal === 'function'
 export const supportsResponseStreams = typeof globalThis.ReadableStream === 'function';
 export const supportsFormData = typeof globalThis.FormData === 'function';
 
-export const requestMethods = ['get', 'post', 'put', 'patch', 'head', 'delete'] as const;
+export const requestMethods = ['get', 'post', 'put', 'patch', 'head', 'delete', 'query'] as const;
 
 const validate = <T extends Array<true>>() => undefined as unknown as T;
 validate<[

source/types/ky.ts

@@ -69,6 +69,14 @@ export type KyInstance = {
 	*/
 	head: (url: Input, options?: Options) => ResponsePromise;
 
+	/**
+	Fetch the given `url` using the option `{method: 'query'}`.
+
+	@param url - `Request` object, `URL` object, or URL string.
+	@returns A promise with `Body` methods added.
+	*/
+	query: <T>(url: Input, options?: Options) => ResponsePromise<T>;
+
 	/**
 	Create a new Ky instance with complete new defaults, without inheriting from any parent instance.
 

source/types/options.ts

@@ -8,7 +8,7 @@ export type SearchParamsInit = string | string[][] | Record<string, string> | UR
 // eslint-disable-next-line unicorn/prevent-abbreviations
 export type SearchParamsOption = SearchParamsInit | Record<string, string | number | boolean | undefined> | Array<Array<string | number | boolean>>;
 
-export type RequestHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';
+export type RequestHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete' | 'query';
 export type HttpMethod = LiteralUnion<RequestHttpMethod | 'options' | 'trace', string>;
 
 export type Input = string | URL | Request;
@@ -400,7 +400,7 @@ export interface Options extends KyOptions, Omit<RequestInit, 'headers'> { // es
 	/**
 	HTTP method used to make the request.
 
-	Internally, the standard methods (`GET`, `POST`, `PUT`, `PATCH`, `HEAD` and `DELETE`) are uppercased in order to avoid server errors due to case sensitivity.
+	Internally, the standard methods (`GET`, `POST`, `PUT`, `PATCH`, `HEAD`, `DELETE`, and `QUERY`) are uppercased in order to avoid server errors due to case sensitivity.
 	*/
 	method?: LiteralUnion<HttpMethod, string>;
 

source/types/retry.ts

@@ -23,7 +23,7 @@ export type RetryOptions = {
 	/**
 	The HTTP methods allowed to retry.
 
-	@default ['get', 'put', 'head', 'delete', 'options', 'trace']
+	@default ['get', 'put', 'head', 'delete', 'options', 'trace', 'query']
 	*/
 	methods?: HttpMethod[];
 

source/utils/normalize.ts

@@ -5,7 +5,7 @@ import type {HttpMethod, RequestHttpMethod} from '../types/options.js';
 export const normalizeRequestMethod = (input: string): string =>
 	requestMethods.includes(input as RequestHttpMethod) ? input.toUpperCase() : input;
 
-const retryMethods: HttpMethod[] = ['get', 'put', 'head', 'delete', 'options', 'trace'];
+const retryMethods: HttpMethod[] = ['get', 'put', 'head', 'delete', 'options', 'trace', 'query'];
 
 const retryStatusCodes = [408, 413, 429, 500, 502, 503, 504];
 

test/browser.ts

@@ -108,6 +108,33 @@ defaultBrowsersTest('prefix option', async (t: ExecutionContext, page: Page) =>
 	t.deepEqual(results, ['rainbow', 'rainbow', 'rainbow', 'rainbow', 'rainbow', 'rainbow', 'rainbow']);
 });
 
+defaultBrowsersTest('QUERY request', async (t: ExecutionContext, page: Page) => {
+	t.plan(2);
+
+	server.get('/', (_request, response) => {
+		response.end();
+	});
+
+	server.all('/test', (request, response) => {
+		t.is(request.method, 'QUERY');
+		response.json(request.body);
+	});
+
+	await page.goto(server.url);
+	await addKyScriptToPage(page);
+
+	const json = {
+		foo: true,
+	};
+
+	const result = await page.evaluate(async ({url, json}) => globalThis.ky.query(`${url}/test`, {json}).json(), {
+		url: server.url,
+		json,
+	});
+
+	t.deepEqual(result, json);
+});
+
 defaultBrowsersTest('aborting a request', async (t: ExecutionContext, page: Page) => {
 	server.get('/', (_request, response) => {
 		response.end('meow');

test/main.ts

@@ -113,6 +113,26 @@ test('DELETE request', async t => {
 	t.is(await ky.delete(server.url).text(), 'DELETE');
 });
 
+test('QUERY request', async t => {
+	t.plan(3);
+
+	const server = await createHttpTestServer(t);
+	server.all('/', (request, response) => {
+		t.is(request.method, 'QUERY');
+		t.is(request.headers['content-type'], 'application/json');
+		response.json(request.body);
+	});
+
+	const json = {
+		foo: true,
+	};
+
+	const responseJson = await ky.query<typeof json>(server.url, {json}).json();
+
+	expectTypeOf(responseJson).toEqualTypeOf<typeof json>();
+	t.deepEqual(responseJson, json);
+});
+
 test('POST JSON', async t => {
 	t.plan(2);
 

test/methods.ts

@@ -43,6 +43,26 @@ test('method defaults to "GET"', async t => {
 	);
 });
 
+test('QUERY method is normalized', async t => {
+	const server = await createHttpTestServer(t);
+	server.all('/', (_request, response) => {
+		response.end();
+	});
+
+	t.plan(1);
+
+	await ky(server.url, {
+		method: 'query',
+		hooks: {
+			beforeRequest: [
+				({options}) => {
+					t.is(options.method, 'QUERY');
+				},
+			],
+		},
+	});
+});
+
 test.failing('custom method remains identical', async t => {
 	const server = await createHttpTestServer(t);
 	server.all('/', (_request, response) => {

test/retry.ts

@@ -89,6 +89,41 @@ test('not on POST', async t => {
 	t.is(requestCount, 1);
 });
 
+test('QUERY retries by default', async t => {
+	let requestCount = 0;
+	const receivedBodies: unknown[] = [];
+	const receivedMethods: string[] = [];
+
+	const server = await createHttpTestServer(t);
+	server.all('/', (request, response) => {
+		requestCount++;
+		receivedMethods.push(request.method);
+		receivedBodies.push(request.body);
+
+		if (requestCount === defaultRetryCount + 1) {
+			response.json(request.body);
+		} else {
+			response.sendStatus(500);
+		}
+	});
+
+	const json = {
+		foo: true,
+	};
+
+	const result = await ky.query(server.url, {
+		json,
+		retry: {
+			delay: () => 0,
+		},
+	}).json();
+
+	t.deepEqual(result, json);
+	t.is(requestCount, defaultRetryCount + 1);
+	t.deepEqual(receivedMethods, ['QUERY', 'QUERY', 'QUERY']);
+	t.deepEqual(receivedBodies, [json, json, json]);
+});
+
 test('respect Retry-After: 0 and retry immediately', async t => {
 	const retryCount = 4;
 	let requestCount = 0;