docs(core): add note about not mutating multi provider arrays (#37645)

Adds a note to the provider docs that users shouldn't mutate an array that
is returned from a `multi` provider, because it can cause unforeseen
consequences in other parts of the app.

Closes #37481.

PR Close #37645
This commit is contained in:
crisbeto 2020-07-14 17:11:54 +02:00 committed by Andrew Kushnir
parent 136acdfab6
commit 72f1eec3ad
1 changed files with 18 additions and 1 deletions

View File

@ -284,6 +284,23 @@ Search for [Constants in API documentation](api?type=const) to find more built-i
</div>
<div class="alert is-helpful">
Note that the reference to the array returned for a `multi` provider is shared between all the
places where the token is injected. We recommend avoiding mutations of the array (especially for
predefined tokens) as it may lead to unexpected behavior in other parts of the app that inject
the same token. You can prevent the value from being mutated by setting its type to `ReadonlyArray`.
</div>
You can use `ReadonlyArray` to type your `multi` provider, so TypeScript triggers an error in case
of unwanted array mutations:
```
constructor(@Inject(MULTI_PROVIDER) multiProvider: ReadonlyArray<MultiProvider>) {
}
```
{@a tree-shakable-provider}
{@a tree-shakable-providers}