Add onUploadProgress option (#632)

Co-authored-by: Sindre Sorhus <[email protected]>
Co-authored-by: Seth Holladay <[email protected]>

Author: 3 people

readme.md

@@ -404,9 +404,12 @@ Type: `Function`
 
 Download progress event handler.
 
-The function receives a `progress` and `chunk` argument:
-- The `progress` object contains the following elements: `percent`, `transferredBytes` and `totalBytes`. If it's not possible to retrieve the body size, `totalBytes` will be `0`.
-- The `chunk` argument is an instance of `Uint8Array`. It's empty for the first call.
+The function receives these arguments:
+- `progress` is an object with the these properties:
+- - `percent` is a number between 0 and 1 representing the progress percentage.
+- - `transferredBytes` is the number of bytes transferred so far.
+- - `totalBytes` is the total number of bytes to be transferred. This is an estimate and may be 0 if the total size cannot be determined.
+- `chunk` is an instance of `Uint8Array` containing the data that was sent. Note: It's empty for the first call.
 
 ```js
 import ky from 'ky';
@@ -421,6 +424,33 @@ const response = await ky('https://example.com', {
 });
 ```
 
+##### onUploadProgress
+
+Type: `Function`
+
+Upload progress event handler.
+
+The function receives these arguments:
+- `progress` is an object with the these properties:
+- - `percent` is a number between 0 and 1 representing the progress percentage.
+- - `transferredBytes` is the number of bytes transferred so far.
+- - `totalBytes` is the total number of bytes to be transferred. This is an estimate and may be 0 if the total size cannot be determined.
+- `chunk` is an instance of `Uint8Array` containing the data that was sent. Note: It's empty for the last call.
+
+```js
+import ky from 'ky';
+
+const response = await ky.post('https://example.com/upload', {
+	body: largeFile,
+	onUploadProgress: (progress, chunk) => {
+		// Example output:
+		// `0% - 0 of 1271 bytes`
+		// `100% - 1271 of 1271 bytes`
+		console.log(`${progress.percent * 100}% - ${progress.transferredBytes} of ${progress.totalBytes} bytes`);
+	}
+});
+```
+
 ##### parseJson
 
 Type: `Function`\

source/core/Ky.ts

@@ -8,6 +8,7 @@ import type {
 	SearchParamsInit,
 } from '../types/options.js';
 import {type ResponsePromise} from '../types/ResponsePromise.js';
+import {streamRequest, streamResponse} from '../utils/body.js';
 import {mergeHeaders, mergeHooks} from '../utils/merge.js';
 import {normalizeRequestMethod, normalizeRetryOptions} from '../utils/normalize.js';
 import timeout, {type TimeoutOptions} from '../utils/timeout.js';
@@ -64,7 +65,6 @@ export class Ky {
 			}
 
 			// If `onDownloadProgress` is passed, it uses the stream API internally
-			/* istanbul ignore next */
 			if (ky._options.onDownloadProgress) {
 				if (typeof ky._options.onDownloadProgress !== 'function') {
 					throw new TypeError('The `onDownloadProgress` option must be a function');
@@ -74,7 +74,7 @@ export class Ky {
 					throw new Error('Streams are not supported in your environment. `ReadableStream` is missing.');
 				}
 
-				return ky._stream(response.clone(), ky._options.onDownloadProgress);
+				return streamResponse(response.clone(), ky._options.onDownloadProgress);
 			}
 
 			return response;
@@ -205,6 +205,22 @@ export class Ky {
 			// The spread of `this.request` is required as otherwise it misses the `duplex` option for some reason and throws.
 			this.request = new globalThis.Request(new globalThis.Request(url, {...this.request}), this._options as RequestInit);
 		}
+
+		// If `onUploadProgress` is passed, it uses the stream API internally
+		if (this._options.onUploadProgress) {
+			if (typeof this._options.onUploadProgress !== 'function') {
+				throw new TypeError('The `onUploadProgress` option must be a function');
+			}
+
+			if (!supportsRequestStreams) {
+				throw new Error('Request streams are not supported in your environment. The `duplex` option for `Request` is not available.');
+			}
+
+			const originalBody = this.request.body;
+			if (originalBody) {
+				this.request = streamRequest(this.request, this._options.onUploadProgress);
+			}
+		}
 	}
 
 	protected _calculateRetryDelay(error: unknown) {
@@ -310,61 +326,4 @@ export class Ky {
 
 		return timeout(mainRequest, nonRequestOptions, this.abortController, this._options as TimeoutOptions);
 	}
-
-	/* istanbul ignore next */
-	protected _stream(response: Response, onDownloadProgress: Options['onDownloadProgress']) {
-		const totalBytes = Number(response.headers.get('content-length')) || 0;
-		let transferredBytes = 0;
-
-		if (response.status === 204) {
-			if (onDownloadProgress) {
-				onDownloadProgress({percent: 1, totalBytes, transferredBytes}, new Uint8Array());
-			}
-
-			return new globalThis.Response(
-				null,
-				{
-					status: response.status,
-					statusText: response.statusText,
-					headers: response.headers,
-				},
-			);
-		}
-
-		return new globalThis.Response(
-			new globalThis.ReadableStream({
-				async start(controller) {
-					const reader = response.body!.getReader();
-
-					if (onDownloadProgress) {
-						onDownloadProgress({percent: 0, transferredBytes: 0, totalBytes}, new Uint8Array());
-					}
-
-					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);
-						await read();
-					}
-
-					await read();
-				},
-			}),
-			{
-				status: response.status,
-				statusText: response.statusText,
-				headers: response.headers,
-			},
-		);
-	}
 }

source/core/constants.ts

@@ -54,6 +54,9 @@ export const responseTypes = {
 // The maximum value of a 32bit int (see issue #117)
 export const maxSafeTimeout = 2_147_483_647;
 
+// Size in bytes of a typical form boundary, used to help estimate upload size
+export const usualFormBoundarySize = new TextEncoder().encode('------WebKitFormBoundaryaxpyiPgbbPti10Rw').length;
+
 export const stop = Symbol('stop');
 
 export const kyOptionKeys: KyOptionsRegistry = {
@@ -67,6 +70,7 @@ export const kyOptionKeys: KyOptionsRegistry = {
 	hooks: true,
 	throwHttpErrors: true,
 	onDownloadProgress: true,
+	onUploadProgress: true,
 	fetch: true,
 };
 

source/index.ts

@@ -42,7 +42,7 @@ export type {
 	NormalizedOptions,
 	RetryOptions,
 	SearchParamsOption,
-	DownloadProgress,
+	Progress,
 } from './types/options.js';
 
 export type {

source/types/options.ts

@@ -12,7 +12,7 @@ export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';
 
 export type Input = string | URL | Request;
 
-export type DownloadProgress = {
+export type Progress = {
 	percent: number;
 	transferredBytes: number;
 
@@ -170,7 +170,8 @@ export type KyOptions = {
 	/**
 	Download progress event handler.
 
-	@param chunk - Note: It's empty for the first call.
+	@param progress - Object containing download progress information.
+	@param chunk - Data that was received. Note: It's empty for the first call.
 
 	@example
 	```
@@ -186,7 +187,30 @@ export type KyOptions = {
 	});
 	```
 	*/
-	onDownloadProgress?: (progress: DownloadProgress, chunk: Uint8Array) => void;
+	onDownloadProgress?: (progress: Progress, chunk: Uint8Array) => void;
+
+	/**
+	Upload progress event handler.
+
+	@param progress - Object containing upload progress information.
+	@param chunk - Data that was sent. Note: It's empty for the last call.
+
+	@example
+	```
+	import ky from 'ky';
+
+	const response = await ky.post('https://example.com/upload', {
+		body: largeFile,
+		onUploadProgress: (progress, chunk) => {
+			// Example output:
+			// `0% - 0 of 1271 bytes`
+			// `100% - 1271 of 1271 bytes`
+			console.log(`${progress.percent * 100}% - ${progress.transferredBytes} of ${progress.totalBytes} bytes`);
+		}
+	});
+	```
+	*/
+	onUploadProgress?: (progress: Progress, chunk: Uint8Array) => void;
 
 	/**
 	User-defined `fetch` function.
@@ -287,6 +311,7 @@ export interface NormalizedOptions extends RequestInit { // eslint-disable-line
 	retry: RetryOptions;
 	prefixUrl: string;
 	onDownloadProgress: Options['onDownloadProgress'];
+	onUploadProgress: Options['onUploadProgress'];
 }
 
 export type {RetryOptions} from './retry.js';