Add request/response context to parseJson option (#849)

Author: sindresorhus

readme.md

@@ -734,9 +734,12 @@ Default: `JSON.parse()`
 
 User-defined JSON-parsing function.
 
+The function receives the response text as the first argument and a context object as the second argument containing the `request` ([`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)) and `response` ([`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)).
+
 Use-cases:
 1. Parse JSON via the [`bourne` package](https://github.com/hapijs/bourne) to protect from prototype pollution.
 2. Parse JSON with [`reviver` option of `JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
+3. Log or handle JSON parse errors with request context.
 
 ```js
 import ky from 'ky';
@@ -747,6 +750,17 @@ const json = await ky('https://example.com', {
 }).json();
 ```
 
+```js
+import ky from 'ky';
+
+const json = await ky('https://example.com', {
+	parseJson: (text, {request, response}) => {
+		console.log(`Parsing JSON from ${request.url} (status: ${response.status})`);
+		return JSON.parse(text);
+	}
+}).json();
+```
+
 ##### stringifyJson
 
 Type: `Function`\

source/core/Ky.ts

@@ -244,7 +244,7 @@ export class Ky {
 				}
 
 				const jsonValue = options.parseJson
-					? await options.parseJson(text)
+					? await options.parseJson(text, {request: ky.request, response})
 					: JSON.parse(text);
 
 				return schema === undefined ? jsonValue : validateJsonWithSchema(jsonValue, schema);
@@ -491,7 +491,7 @@ export class Ky {
 
 	#decorateResponse(response: Response): Response {
 		if (this.#options.parseJson) {
-			response.json = async () => this.#options.parseJson!(await response.text());
+			response.json = async () => this.#options.parseJson!(await response.text(), {request: this.request, response});
 		}
 
 		return response;
@@ -511,7 +511,7 @@ export class Ky {
 			return text;
 		}
 
-		return this.#parseJson(text, errorDataTimeout);
+		return this.#parseJson(text, response, errorDataTimeout);
 	}
 
 	#isJsonContentType(contentType: string): boolean {
@@ -584,11 +584,14 @@ export class Ky {
 		return result;
 	}
 
-	async #parseJson(text: string, timeoutMs: number): Promise<unknown> {
+	async #parseJson(text: string, response: Response, timeoutMs: number): Promise<unknown> {
 		let timeoutId: ReturnType<typeof setTimeout> | undefined;
 		try {
 			return await Promise.race([
-				Promise.resolve().then(() => (this.#options.parseJson ?? JSON.parse)(text)),
+				Promise.resolve().then(() => this.#options.parseJson
+					? this.#options.parseJson(text, {request: this.request, response})
+					: JSON.parse(text),
+				),
 				new Promise<undefined>(resolve => {
 					timeoutId = setTimeout(() => {
 						resolve(undefined);

source/types/options.ts

@@ -41,9 +41,12 @@ export type KyOptions = {
 	/**
 	User-defined JSON-parsing function.
 
+	The function receives the response text as the first argument and a context object as the second argument containing the `request` and `response`.
+
 	Use-cases:
 	1. Parse JSON via the [`bourne` package](https://github.com/hapijs/bourne) to protect from prototype pollution.
 	2. Parse JSON with [`reviver` option of `JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse).
+	3. Log or handle JSON parse errors with request context.
 
 	@default JSON.parse()
 
@@ -56,8 +59,21 @@ export type KyOptions = {
 		parseJson: text => bourne(text)
 	}).json();
 	```
+
+	@example
+	```
+	import ky from 'ky';
+
+	const json = await ky('https://example.com', {
+		parseJson: (text, {request, response}) => {
+			console.log(`Parsing JSON from ${request.url} (status: ${response.status})`);
+			return JSON.parse(text);
+		}
+	}).json();
+	```
 	*/
-	parseJson?: (text: string) => unknown;
+	// `options` is intentionally not included in the context to avoid exposing Ky internals through a parsing callback. `request`/`response` already provide the metadata needed for logging.
+	parseJson?: (text: string, context: {request: Request; response: Response}) => unknown;
 
 	/**
 	User-defined JSON-stringifying function.

test/http-error.ts

@@ -126,6 +126,49 @@ test('HTTPError#data respects parseJson option', async t => {
 	t.deepEqual(error?.data, {value: 1, custom: true});
 });
 
+test('HTTPError#data parseJson receives context', async t => {
+	const server = await createHttpTestServer(t);
+	const body = {value: 1};
+	server.get('/', (_request, response) => {
+		response.status(400).json(body);
+	});
+
+	const error = await t.throwsAsync<HTTPError>(ky.get(server.url, {
+		parseJson(text, {request, response}) {
+			t.true(request instanceof Request);
+			t.true(response instanceof Response);
+			t.is(response.status, 400);
+			t.true(request.url.includes(server.url));
+			const data = JSON.parse(text) as Record<string, unknown>;
+			data.custom = true;
+			return data;
+		},
+	}));
+	t.deepEqual(error?.data, {value: 1, custom: true});
+});
+
+test('HTTPError#data async parseJson receives context', async t => {
+	const server = await createHttpTestServer(t);
+	const body = {value: 1};
+	server.get('/', (_request, response) => {
+		response.status(400).json(body);
+	});
+
+	const error = await t.throwsAsync<HTTPError>(ky.get(server.url, {
+		async parseJson(text, {request, response}) {
+			t.true(request instanceof Request);
+			t.true(response instanceof Response);
+			t.is(response.status, 400);
+			t.true(request.url.includes(server.url));
+			await Promise.resolve();
+			const data = JSON.parse(text) as Record<string, unknown>;
+			data.custom = true;
+			return data;
+		},
+	}));
+	t.deepEqual(error?.data, {value: 1, custom: true});
+});
+
 test('HTTPError#data awaits async parseJson option', async t => {
 	const server = await createHttpTestServer(t);
 	const body = {value: 1};

test/main.ts

@@ -1864,6 +1864,85 @@ test('parseJson option errors are thrown before .json(schema) validation', async
 	t.false(isSchemaCalled());
 });
 
+test('parseJson option receives context via .json() shortcut', async t => {
+	const json = {hello: 'world'};
+
+	const server = await createHttpTestServer(t);
+	server.get('/', (_request, response) => {
+		response.json(json);
+	});
+
+	const responseJson = await ky
+		.get(server.url, {
+			parseJson(text, {request, response}) {
+				t.true(request instanceof Request);
+				t.true(response instanceof Response);
+				t.is(response.status, 200);
+				t.true(request.url.includes(server.url));
+				return JSON.parse(text);
+			},
+		})
+		.json();
+
+	t.deepEqual(responseJson, json);
+});
+
+test('parseJson option receives context via response.json()', async t => {
+	const json = {hello: 'world'};
+
+	const server = await createHttpTestServer(t);
+	server.get('/', (_request, response) => {
+		response.json(json);
+	});
+
+	const response = await ky.get(server.url, {
+		parseJson(text, {request, response}) {
+			t.true(request instanceof Request);
+			t.true(response instanceof Response);
+			t.is(response.status, 200);
+			t.true(request.url.includes(server.url));
+			return JSON.parse(text);
+		},
+	});
+
+	const responseJson = await response.json();
+	t.deepEqual(responseJson, json);
+});
+
+test('parseJson option receives context after retry', async t => {
+	let requestCount = 0;
+	const statuses: number[] = [];
+
+	const server = await createHttpTestServer(t);
+	server.get('/', (_request, response) => {
+		requestCount++;
+		if (requestCount === 1) {
+			response.status(500).json({error: 'fail'});
+			return;
+		}
+
+		response.json({hello: 'world'});
+	});
+
+	const responseJson = await ky
+		.get(server.url, {
+			retry: 1,
+			parseJson(text, {request, response}) {
+				t.true(request instanceof Request);
+				t.true(response instanceof Response);
+				t.true(request.url.includes(server.url));
+				statuses.push(response.status);
+				return JSON.parse(text);
+			},
+		})
+		.json();
+
+	t.deepEqual(responseJson, {hello: 'world'});
+	t.is(requestCount, 2);
+	// ParseJson is called for the error response (HTTPError#data) and the success response
+	t.deepEqual(statuses, [500, 200]);
+});
+
 test('stringifyJson option with request.json()', async t => {
 	const server = await createHttpTestServer(t, {bodyParser: false});