Document how to get better upload progress

Fixes #2420

Author: sindresorhus

documentation/3-streams.md

@@ -124,27 +124,41 @@ An object representing how much data have been downloaded.
 
 An object representing how much data have been uploaded.
 
-**Note:**
-> - When a chunk is greater than `highWaterMark`, the progress won't be emitted. The body needs to be split into chunks.
+> **Note:** To get granular upload progress instead of just 0% and 100%, split the body into chunks using the [`chunk-data`](https://github.com/sindresorhus/chunk-data) package:
+> - `chunk(buffer, chunkSize)` - For buffers/typed arrays
+> - `chunkFromAsync(iterable, chunkSize)` - For iterables (Node.js streams are async iterables)
 
 ```js
 import got from 'got';
+import {chunk, chunkFromAsync} from 'chunk-data';
+import {Readable} from 'node:stream';
 
-const body = Buffer.alloc(1024 * 1024); // 1MB
+// Chunk a buffer
 
-function* chunkify(buffer, chunkSize = 64 * 1024) {
-	for (let pos = 0; pos < buffer.byteLength; pos += chunkSize) {
-		yield buffer.subarray(pos, pos + chunkSize)
-	}
-}
+const buffer = new Uint8Array(1024 * 1024);
 
-const stream = got.stream.post('https://httpbin.org/anything', {
-	body: chunkify(body)
+await got.post('https://httpbin.org/anything', {
+	body: chunk(buffer, 65_536),
+	headers: {
+		'content-length': buffer.byteLength.toString()
+	}
+})
+.on('uploadProgress', progress => {
+	console.log(progress);
 });
 
-stream.resume();
 
-stream.on('uploadProgress', progress => {
+// Chunk an iterable/stream
+
+const [stream, size] = getStream();
+
+await got.post('https://httpbin.org/anything', {
+	body: chunkFromAsync(stream, 65_536),
+	headers: {
+		'content-length': size
+	}
+})
+.on('uploadProgress', progress => {
 	console.log(progress);
 });
 ```

package.json

@@ -82,6 +82,7 @@
 		"bluebird": "^3.7.2",
 		"body-parser": "^1.20.3",
 		"c8": "^10.1.3",
+		"chunk-data": "^0.1.0",
 		"create-cert": "^1.0.6",
 		"create-test-server": "^3.0.1",
 		"del-cli": "^6.0.0",

test/progress.ts

@@ -13,6 +13,7 @@ import is from '@sindresorhus/is';
 import test, {type ExecutionContext} from 'ava';
 import type {Handler} from 'express';
 import {pEvent} from 'p-event';
+import {chunk, chunkFromAsync} from 'chunk-data';
 import type {Progress} from '../source/index.js';
 import withServer from './helpers/with-server.js';
 
@@ -300,3 +301,41 @@ test('does not emit uploadProgress after cancelation', withServer, async (t, ser
 
 	t.pass();
 });
+
+test('upload progress - chunk generator with buffer', withServer, async (t, server, got) => {
+	server.post('/', uploadEndpoint);
+
+	const events: Progress[] = [];
+
+	await got.post({
+		body: chunk(file, 65_536),
+		headers: {
+			'content-length': file.length.toString(),
+		},
+	})
+		.on('uploadProgress', (event: Progress) => events.push(event));
+
+	checkEvents(t, events, file.length);
+
+	// Ensure we got more than just 0% and 100%
+	t.true(events.length > 2, `Expected more than 2 events with chunk, got ${events.length}`);
+});
+
+test('upload progress - chunkFromAsync async generator with stream', withServer, async (t, server, got) => {
+	server.post('/', uploadEndpoint);
+
+	const events: Progress[] = [];
+
+	await got.post({
+		body: chunkFromAsync(stream.Readable.from([file]), 65_536),
+		headers: {
+			'content-length': file.length.toString(),
+		},
+	})
+		.on('uploadProgress', (event: Progress) => events.push(event));
+
+	checkEvents(t, events, file.length);
+
+	// Ensure we got more than just 0% and 100%
+	t.true(events.length > 2, `Expected more than 2 events with chunkFromAsync, got ${events.length}`);
+});