Expose assignOptions (#530)

advanced-creation.md

@@ -11,7 +11,8 @@ Configure a new `got` instance with the provided settings.<br>
 
 ##### [options](readme.md#options)
 
-To inherit from parent, set it as `got.defaults.options` or use [object spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals).
+To inherit from parent, set it as `got.defaults.options` or use [`got.assignOptions(defaults.options, options)`](readme.md#gotassignoptionsparentoptions-newoptions).<br>
+**Note**: Avoid using [object spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals) as it doesn't work recursively.
 
 ##### methods
 
@@ -53,10 +54,9 @@ const settings = {
 		return next(options);
 	},
 	methods: got.defaults.methods,
-	options: {
-		...got.defaults.options,
+	options: got.assignOptions(got.defaults.options, {
 		json: true
-	}
+	})
 };
 
 const jsonGot = got.create(settings);
@@ -99,12 +99,11 @@ const unchangedGot = got.create(defaults);
 const settings = {
 	handler: got.defaults.handler,
 	methods: got.defaults.methods,
-	options: {
-		...got.defaults.options,
+	options: got.assignOptions(got.defaults.options, {
 		headers: {
 			unicorn: 'rainbow'
 		}
-	}
+	})
 };
 
 const unicorn = got.create(settings);

readme.md

@@ -398,6 +398,18 @@ client.get('/demo');
 
 *Need more control over the behavior of Got? Check out the [`got.create()`](advanced-creation.md).*
 
+#### got.assignOptions(parentOptions, newOptions)
+
+Extends parent options. Avoid using [object spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals) as it doesn't work recursively:
+
+```js
+const a = {headers: {cat: 'meow'}};
+const b = {headers: {dog: 'woof'}};
+
+{...a, ...b}            // => {headers: {dog: 'woof'}}
+got.assignOptions(a, b) // => {headers: {cat: 'meow', dog: 'woof'}}
+```
+
 ## Errors
 
 Each error contains (if available) `statusCode`, `statusMessage`, `host`, `hostname`, `method`, `path`, `protocol` and `url` properties to make debugging easier.

source/create.js

@@ -46,7 +46,7 @@ const create = defaults => {
 		got.stream[method] = (url, options) => got.stream(url, {...options, method});
 	}
 
-	Object.assign(got, errors);
+	Object.assign(got, {...errors, assignOptions});
 	Object.defineProperty(got, 'defaults', {
 		value: deepFreeze(defaults),
 		writable: false,

test/create.js

@@ -105,10 +105,9 @@ test('no tampering with defaults', t => {
 	const instance = got.create({
 		handler: got.defaults.handler,
 		methods: got.defaults.methods,
-		options: {
-			...got.defaults.options,
+		options: got.assignOptions(got.defaults.options, {
 			baseUrl: 'example'
-		}
+		})
 	});
 
 	const instance2 = instance.create({