From 72f1eec3ad35e5d94331d94431b8437c1a102b2f Mon Sep 17 00:00:00 2001
From: crisbeto <crisbeto@abv.bg>
Date: Tue, 14 Jul 2020 17:11:54 +0200
Subject: [PATCH] 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
---
 .../guide/dependency-injection-providers.md   | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/aio/content/guide/dependency-injection-providers.md b/aio/content/guide/dependency-injection-providers.md
index 5480b50497..68fe995061 100644
--- a/aio/content/guide/dependency-injection-providers.md
+++ b/aio/content/guide/dependency-injection-providers.md
@@ -262,7 +262,7 @@ For example, when bootstrapping an application, you can register many initialize
 
 ```
 export const APP_TOKENS = [
- { provide: PLATFORM_INITIALIZER, useFactory: platformInitialized, multi: true    },
+ { provide: PLATFORM_INITIALIZER, useFactory: platformInitialized, multi: true },
  { provide: APP_INITIALIZER, useFactory: delayBootstrapping, multi: true },
  { provide: APP_BOOTSTRAP_LISTENER, useFactory: appBootstrapped, multi: true },
 ];
@@ -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}