Add typed JSON response (#437)

Author: TeraNovell

package.json

@@ -71,7 +71,8 @@
 		"raw-body": "^2.5.1",
 		"ts-node": "^10.6.0",
 		"typescript": "~4.6.2",
-		"xo": "^0.48.0"
+		"xo": "^0.48.0",
+		"expect-type": "^0.13.0"
 	},
 	"sideEffects": false,
 	"xo": {

source/core/Ky.ts

@@ -2,7 +2,7 @@ import {HTTPError} from '../errors/HTTPError.js';
 import {TimeoutError} from '../errors/TimeoutError.js';
 import type {Hooks} from '../types/hooks.js';
 import type {Input, InternalOptions, NormalizedOptions, Options, SearchParamsInit} from '../types/options.js';
-import {ResponsePromise} from '../types/response.js';
+import {ResponsePromise} from '../types/ResponsePromise.js';
 import {deepMerge, mergeHeaders} from '../utils/merge.js';
 import {normalizeRequestMethod, normalizeRetryOptions} from '../utils/normalize.js';
 import {delay, timeout, TimeoutOptions} from '../utils/time.js';

source/index.ts

@@ -44,6 +44,7 @@ export {
 	AfterResponseHook,
 } from './types/hooks.js';
 
-export {ResponsePromise} from './types/response.js';
+export {ResponsePromise} from './types/ResponsePromise.js';
+export {KyResponse} from './types/response.js';
 export {HTTPError} from './errors/HTTPError.js';
 export {TimeoutError} from './errors/TimeoutError.js';

source/types/ResponsePromise.ts

@@ -0,0 +1,39 @@
+/**
+Returns a `Response` object with `Body` methods added for convenience. So you can, for example, call `ky.get(input).json()` directly without having to await the `Response` first. When called like that, an appropriate `Accept` header will be set depending on the body method used. Unlike the `Body` methods of `window.Fetch`; these will throw an `HTTPError` if the response status is not in the range of `200...299`. Also, `.json()` will return an empty string if the response status is `204` instead of throwing a parse error due to an empty body.
+*/
+import {KyResponse} from './response.js';
+
+export interface ResponsePromise extends Promise<KyResponse> {
+	arrayBuffer: () => Promise<ArrayBuffer>;
+
+	blob: () => Promise<Blob>;
+
+	formData: () => Promise<FormData>;
+
+	// TODO: Use `json<T extends JSONValue>(): Promise<T>;` when it's fixed in TS.
+	// See https://github.com/microsoft/TypeScript/issues/15300 and https://github.com/sindresorhus/ky/pull/80
+	/**
+	Get the response body as JSON.
+
+	@example
+	```
+	import ky from 'ky';
+
+	const json = await ky(…).json();
+	```
+
+	@example
+	```
+	import ky from 'ky';
+
+	interface Result {
+		value: number;
+	}
+
+	const result = await ky(…).json<Result>();
+	```
+	*/
+	json: <T = unknown>() => Promise<T>;
+
+	text: () => Promise<string>;
+}

source/types/ky.ts

@@ -1,6 +1,6 @@
 import {stop} from '../core/constants.js';
 import type {Input, Options} from './options.js';
-import type {ResponsePromise} from './response.js';
+import type {ResponsePromise} from './ResponsePromise.js';
 
 export interface KyInstance {
 	/**

source/types/response.ts

@@ -1,37 +1,3 @@
-/**
-Returns a `Response` object with `Body` methods added for convenience. So you can, for example, call `ky.get(input).json()` directly without having to await the `Response` first. When called like that, an appropriate `Accept` header will be set depending on the body method used. Unlike the `Body` methods of `window.Fetch`; these will throw an `HTTPError` if the response status is not in the range of `200...299`. Also, `.json()` will return an empty string if the response status is `204` instead of throwing a parse error due to an empty body.
-*/
-export interface ResponsePromise extends Promise<Response> {
-	arrayBuffer: () => Promise<ArrayBuffer>;
-
-	blob: () => Promise<Blob>;
-
-	formData: () => Promise<FormData>;
-
-	// TODO: Use `json<T extends JSONValue>(): Promise<T>;` when it's fixed in TS.
-	// See https://github.com/microsoft/TypeScript/issues/15300 and https://github.com/sindresorhus/ky/pull/80
-	/**
-	Get the response body as JSON.
-
-	@example
-	```
-	import ky from 'ky';
-
-	const json = await ky(…).json();
-	```
-
-	@example
-	```
-	import ky from 'ky';
-
-	interface Result {
-		value: number;
-	}
-
-	const result = await ky(…).json<Result>();
-	```
-	*/
+export interface KyResponse extends Response {
 	json: <T = unknown>() => Promise<T>;
-
-	text: () => Promise<string>;
 }

test/main.ts

@@ -1,6 +1,7 @@
 import {Buffer} from 'node:buffer';
 import test from 'ava';
 import delay from 'delay';
+import {expectTypeOf} from 'expect-type';
 import ky, {TimeoutError} from '../source/index.js';
 import {createHttpTestServer} from './helpers/create-http-test-server.js';
 import {parseRawBody} from './helpers/parse-body.js';
@@ -662,7 +663,10 @@ test('parseJson option with response.json()', async t => {
 			extra: 'extraValue',
 		}),
 	});
-	const responseJson = await response.json();
+
+	const responseJson = await response.json<{hello: string; extra: string}>();
+
+	expectTypeOf(responseJson).toMatchTypeOf({hello: 'world', extra: 'extraValue'});
 
 	t.deepEqual(responseJson, {
 		...json,