Document using FormData (#130)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

index.js

@@ -26,9 +26,11 @@ const Headers = getGlobal('Headers');
 const Response = getGlobal('Response');
 const fetch = getGlobal('fetch');
 const AbortController = getGlobal('AbortController');
+const FormData = getGlobal('FormData');
 
 const isObject = value => value !== null && typeof value === 'object';
 const supportsAbortController = typeof getGlobal('AbortController') === 'function';
+const supportsFormData = typeof FormData === 'function';
 
 const deepMerge = (...sources) => {
 	let returnValue = {};
@@ -200,6 +202,10 @@ class Ky {
 
 		const headers = new Headers(this._options.headers || {});
 
+		if (((supportsFormData && this._options.body instanceof FormData) || this._options.body instanceof URLSearchParams) && headers.has('content-type')) {
+			throw new Error(`The \`content-type\` header cannot be used with a ${this._options.body.constructor.name} body. It will be set automatically.`);
+		}
+
 		if (json) {
 			if (this._options.body) {
 				throw new Error('The `json` option cannot be used with the `body` option');

readme.md

@@ -277,6 +277,34 @@ The error thrown when the request times out.
 
 ## Tips
 
+### Sending Form Data
+
+Sending form data in Ky is identical to `fetch`. Just pass a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instance to the `body` option. The `Content-Type` header will be automatically set to `multipart/form-data`. Setting it manually will result in an error.
+
+```js
+// `multipart/form-data`
+const formData = new FormData();
+formData.append('food', 'fries');
+formData.append('drink', 'icetea');
+
+ky.post(url, {
+	body: formData
+});
+```
+
+If you want to send the data in `application/x-www-form-urlencoded` format, you will need to encode the data with [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams).
+
+```js
+// `application/x-www-form-urlencoded`
+const searchParams = new URLSearchParams();
+searchParams.set('food', 'fries');
+searchParams.set('drink', 'icetea');
+
+ky.post(url, {
+	body: searchParams
+});
+```
+
 ### Cancellation
 
 Fetch (and hence Ky) has built-in support for request cancellation through the [`AbortController` API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). [Read more.](https://developers.google.com/web/updates/2017/09/abortable-fetch)

test/hooks.js

@@ -95,7 +95,7 @@ test('afterResponse hook accept success response', async t => {
 		foo: true
 	};
 
-	await t.notThrowsAsync(() => ky.post(
+	await t.notThrowsAsync(ky.post(
 		server.url,
 		{
 			json,
@@ -123,7 +123,7 @@ test('afterResponse hook accept fail response', async t => {
 		foo: true
 	};
 
-	await t.throwsAsync(() => ky.post(
+	await t.throwsAsync(ky.post(
 		server.url,
 		{
 			json,
@@ -189,7 +189,7 @@ test('afterResponse hook can throw error to reject the request promise', async t
 	const expectError = new Error('Error from `afterResponse` hook');
 
 	// Sync hook function
-	await t.throwsAsync(() => ky.get(
+	await t.throwsAsync(ky.get(
 		server.url,
 		{
 			hooks: {
@@ -205,7 +205,7 @@ test('afterResponse hook can throw error to reject the request promise', async t
 	});
 
 	// Async hook function
-	await t.throwsAsync(() => ky.get(
+	await t.throwsAsync(ky.get(
 		server.url,
 		{
 			hooks: {

test/main.js

@@ -352,3 +352,12 @@ test('throws AbortError when aborted by user', async t => {
 
 	await t.throwsAsync(response, {name: 'AbortError'});
 });
+
+test('throws when using FormData with `content-type` header', t => {
+	t.throws(() => ky.post('https://example.com', {
+		body: new URLSearchParams(),
+		headers: {
+			'content-type': ''
+		}
+	}), 'The `content-type` header cannot be used with a URLSearchParams body. It will be set automatically.');
+});

test/methods.js

@@ -8,7 +8,7 @@ test('common method is normalized', async t => {
 		response.end();
 	});
 
-	await t.notThrowsAsync(() => ky(server.url, {
+	await t.notThrowsAsync(ky(server.url, {
 		method: 'get',
 		hooks: {
 			beforeRequest: [
@@ -28,7 +28,7 @@ test('custom method remains identical', async t => {
 		response.end();
 	});
 
-	await t.notThrowsAsync(() => ky(server.url, {
+	await t.notThrowsAsync(ky(server.url, {
 		method: 'report',
 		hooks: {
 			beforeRequest: [