Add onDownloadProgress option

index.d.ts

@@ -67,6 +67,13 @@ export interface Options extends RequestInit {
 	*/
 	timeout?: number;
 
+	/**
+	Download progress event handler.
+	The function takes `percent`, `transferredBytes`, `totalBytes` and `chunk` arguments.
+	If it's not possible to retrieve the body size, total will be `0`.
+	*/
+	onDownloadProgress?: (percent: number, transferredBytes: number, totalBytes: number, chunk?: Uint8Array) => void;
+
 	/**
 	Hooks allow modifications during the request lifecycle. Hook functions may be async and are run serially.
 	*/

index.js

@@ -24,11 +24,13 @@ const getGlobal = property => {
 const document = getGlobal('document');
 const Headers = getGlobal('Headers');
 const Response = getGlobal('Response');
+const ReadableStream = getGlobal('ReadableStream');
 const fetch = getGlobal('fetch');
 const AbortController = getGlobal('AbortController');
 
 const isObject = value => value !== null && typeof value === 'object';
-const supportsAbortController = typeof getGlobal('AbortController') === 'function';
+const supportsAbortController = typeof AbortController === 'function';
+const supportsStreams = typeof ReadableStream === 'function';
 
 const deepMerge = (...sources) => {
 	let returnValue = {};
@@ -222,6 +224,20 @@ class Ky {
 				throw new HTTPError(response);
 			}
 
+			// If `onDownloadProgress` is passed, use stream API internally
+			/* istanbul ignore next */
+			if (this._options.onDownloadProgress) {
+				if (typeof this._options.onDownloadProgress !== 'function') {
+					throw new TypeError('The `onDownloadProgress` option must be a function');
+				}
+
+				if (!supportsStreams) {
+					throw new Error('Streams are not supported in your environment. `ReadableStream` is missing.');
+				}
+
+				return this._stream(response.clone(), this._options.onDownloadProgress);
+			}
+
 			return response;
 		};
 
@@ -295,6 +311,43 @@ class Ky {
 
 		return timeout(fetch(this._input, this._options), this._timeout, this.abortController);
 	}
+
+	/* istanbul ignore next */
+	_stream(response, onDownloadProgress) {
+		const totalBytes = Number(response.headers.get('content-length')) || 0;
+		let transferredBytes = 0;
+
+		return new Response(
+			new ReadableStream({
+				start(controller) {
+					const reader = response.body.getReader();
+
+					if (onDownloadProgress) {
+						onDownloadProgress(0, 0, totalBytes);
+					}
+
+					async function read() {
+						const {done, value} = await reader.read();
+						if (done) {
+							controller.close();
+							return;
+						}
+
+						if (onDownloadProgress) {
+							transferredBytes += value.byteLength;
+							const percent = totalBytes === 0 ? 0 : transferredBytes / totalBytes;
+							onDownloadProgress(percent, transferredBytes, totalBytes, value);
+						}
+
+						controller.enqueue(value);
+						read();
+					}
+
+					read();
+				}
+			})
+		);
+	}
 }
 
 const createInstance = (defaults = {}) => {

index.test-d.ts

@@ -80,3 +80,13 @@ interface Result {
 	value: number;
 }
 expectType<Promise<Result>>(ky(url).json<Result>());
+
+// `onDownloadProgress` option
+ky(url, {
+	onDownloadProgress: (percent, transferredBytes, totalBytes, chunk) => {
+		expectType<number>(percent);
+		expectType<number>(transferredBytes);
+		expectType<number>(totalBytes);
+		expectType<Uint8Array | undefined>(chunk);
+	}
+});

readme.md

@@ -195,6 +195,24 @@ Default: `10000`
 
 Timeout in milliseconds for getting a response.
 
+##### onDownloadProgress
+
+Type: `Function`
+
+Download progress event handler. The function takes `percent`, `transferredBytes`, `totalBytes` and `chunk` arguments. If it's not possible to retrieve the body size, total will be `0`.
+
+
+```js
+await ky('https://example.com', {
+	onProgress: (percent, transferred, total, chunk) => {
+		// Example output:
+		// `0% - 0 of 1271 bytes`
+		// `100% - 1271 of 1271 bytes`
+		console.log(`${percent * 100}% - ${transferred} of ${total} bytes`);
+	}
+})
+```
+
 ##### hooks
 
 Type: `Object<string, Function[]>`<br>

test/browser.js

@@ -61,3 +61,67 @@ test('aborting a request', withPage, async (t, page) => {
 
 	await server.close();
 });
+
+test('onDownloadProgress works', withPage, async (t, page) => {
+	const server = await createTestServer();
+
+	server.get('/', (request, response) => {
+		response.writeHead(200, {
+			'content-length': 4
+		});
+
+		response.write('me');
+		setTimeout(() => {
+			response.end('ow');
+		}, 1000);
+	});
+
+	await page.goto(server.url);
+	await page.addScriptTag({path: './umd.js'});
+
+	const result = await page.evaluate(async url => {
+		// `new TextDecoder('utf-8').decode` hangs up?
+		const decodeUTF8 = array => String.fromCharCode.apply(null, array);
+
+		const data = [];
+		window.ky = window.ky.default;
+
+		const text = await window.ky(url, {
+			onDownloadProgress: (percent, transferredBytes, totalBytes, chunk) => {
+				const stringifiedChunk = chunk instanceof Uint8Array ? decodeUTF8(chunk) : String(chunk);
+				data.push([percent, transferredBytes, totalBytes, stringifiedChunk]);
+			}
+		}).text();
+
+		return {data, text};
+	}, server.url);
+
+	t.deepEqual(result.data, [
+		[0, 0, 4, 'undefined'],
+		[0.5, 2, 4, 'me'],
+		[1, 4, 4, 'ow']
+	]);
+	t.is(result.text, 'meow');
+
+	await server.close();
+});
+
+test('throws if onDownloadProgress is not a function', withPage, async (t, page) => {
+	const server = await createTestServer();
+
+	server.get('/', (request, response) => {
+		response.end();
+	});
+
+	await page.goto(server.url);
+	await page.addScriptTag({path: './umd.js'});
+
+	const error = await page.evaluate(url => {
+		window.ky = window.ky.default;
+		const request = window.ky(url, {onDownloadProgress: 1}).text();
+		return request.catch(error => error.toString());
+	}, server.url);
+	t.is(error, 'TypeError: The `onDownloadProgress` option must be a function');
+
+	await server.close();
+});