Simpler instance creation

[szmarczak]

The same instances, but their creation is much simpler.

• Merging instances:
  Now: instanceA.extend(instanceB, instanceC, ...)
  Before: got.mergeInstances(instanceA, instanceB, instanceC, ...)
• Merging options:
  Now: instanceA.extend(optionsB, optionsC, ...)
  Before: instanceA.extend(optionsB).extend(optionsC).extend(...)
• Merging instances and options:
  Now: instanceA.extend(optionsB, instanceC, ...)
  Before: got.mergeInstances(instanceA.extend(optionsB), instanceC)
• Extending handlers:
  Now: instanceA.extend({handlers: [handlerB]})
  Before: got.mergeInstances(instanceA, got.create({handler: handlerB}))
• Cloning instances to make them mutable:
  Now: instanceA.extend({mutableDefaults: true}) (not changed)
  Before: instanceA.extend({mutableDefaults: true})

Are there any breaking changes?

1. got.create({handler: ...}) is pluralized and accepts an array.

• Before: defaults.handler was a function containing private array of handlers.
• Now: defaults.handlers is a public array of handlers.

This allows us to inherit properties from the original Promise.
Yup, it's safe to use async handlers now. All the properties (.cancel() etc.) will be proxied.

2. got.mergeInstances(...instances) is deprecated. Use instanceA.extend(instanceB) instead.

Checklist

• I have read the documentation.
• I have included a pull request description of my changes.
• I have included some tests.
• If it's a new feature, I have included documentation updates.
• Fixes The handler method in got.create() should be able to be an async function #701
• Closes XSRF TOKEN support #737

---

IssueHunt Summary

Referenced issues

This pull request has been submitted to:

• #701: The handler method in got.create() should be able to be an async function

---

IssueHunt has been backed by the following sponsors. Become a sponsor

[sindresorhus]

Can you show how this will make it easier to create reusable plugins for Got?

[sindresorhus]

I like the direction of this. I was sceptical at first with overloading .extend(), but seems very natural now.

[sindresorhus]

I still like to see #707 (comment).

[szmarczak]

A breaking change not mentioned:

It is:

1. Handlers are no longer private.
   Before: defaults.handler was a function containing a private array of handlers.
   Now: defaults.handlers is a public array of handlers.

I still like to see #707 (comment).

I will try to think of something.

[szmarczak]

Can you show how this will make it easier to create reusable plugins for Got?

https://github.com/szmarczak/got/blob/simpler-instances/documentation/lets-make-a-plugin.md

In this case gh-got is handler-oriented.
I could add a paragraph about mixing gh-got with the Limiting download & upload instance.
Anyway you can compare the old advanced-creation.md and the new one :)
What do you think?

I'll mention about mixing it with logger instances when I submit a PR for #559.

[szmarczak]

Had to force push because GitHub said "there's a conflict", but there wasn't. As you can see there are no changes between 31e190f and 30cea78.

sorry didn't mean to close the PR

[sindresorhus]

Looks great! 🙌