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({