Repository navigation
Expand file tree
/
Copy pathhydration.ts
More file actions
312 lines (293 loc) · 10.2 KB
/
Copy pathhydration.ts
File metadata and controls
312 lines (293 loc) · 10.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
/**
* @license
* Copyright Google LLC All Rights Reserved.
*
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.dev/license
*/
import {HttpTransferCacheOptions, ɵwithHttpTransferCache} from '@angular/common/http';
import {
APP_BOOTSTRAP_LISTENER,
ApplicationRef,
ɵCACHE_ACTIVE as CACHE_ACTIVE,
ɵConsole as Console,
ENVIRONMENT_INITIALIZER,
EnvironmentProviders,
ɵformatRuntimeError as formatRuntimeError,
inject,
ɵIS_ENABLED_BLOCKING_INITIAL_NAVIGATION as IS_ENABLED_BLOCKING_INITIAL_NAVIGATION,
makeEnvironmentProviders,
Provider,
provideStabilityDebugging,
ɵRuntimeError as RuntimeError,
ɵwithDomHydration as withDomHydration,
ɵwithEventReplay,
ɵwithI18nSupport,
ɵwithIncrementalHydration,
} from '@angular/core';
import {RuntimeErrorCode} from './errors';
/**
* The list of features as an enum to uniquely type each `HydrationFeature`.
* @see {@link HydrationFeature}
*
* @publicApi
*/
export enum HydrationFeatureKind {
NoHttpTransferCache,
HttpTransferCacheOptions,
I18nSupport,
EventReplay,
IncrementalHydration,
NoIncrementalHydration,
}
/**
* Helper type to represent a Hydration feature.
*
* @publicApi
*/
export interface HydrationFeature<FeatureKind extends HydrationFeatureKind> {
ɵkind: FeatureKind;
ɵproviders: Provider[];
}
/**
* Helper function to create an object that represents a Hydration feature.
*/
function hydrationFeature<FeatureKind extends HydrationFeatureKind>(
ɵkind: FeatureKind,
ɵproviders: Provider[] = [],
ɵoptions: unknown = {},
): HydrationFeature<FeatureKind> {
return {ɵkind, ɵproviders};
}
/**
* Disables HTTP transfer cache. Effectively causes HTTP requests to be performed twice: once on the
* server and other one on the browser.
*
* @see [Disabling Caching](guide/ssr#disabling-caching)
*
* @publicApi
*/
export function withNoHttpTransferCache(): HydrationFeature<HydrationFeatureKind.NoHttpTransferCache> {
// This feature has no providers and acts as a flag that turns off
// HTTP transfer cache (which otherwise is turned on by default).
return hydrationFeature(HydrationFeatureKind.NoHttpTransferCache);
}
/**
* The function accepts an object, which allows to configure cache parameters,
* such as which headers should be included (no headers are included by default),
* whether POST requests should be cached or a callback function to determine if a
* particular request should be cached.
*
* @see [Configuring HTTP transfer cache options](guide/ssr#caching-data-when-using-httpclient)
*
* @publicApi
*/
export function withHttpTransferCacheOptions(
options: HttpTransferCacheOptions,
): HydrationFeature<HydrationFeatureKind.HttpTransferCacheOptions> {
// This feature has no providers and acts as a flag to pass options to the HTTP transfer cache.
return hydrationFeature(
HydrationFeatureKind.HttpTransferCacheOptions,
ɵwithHttpTransferCache(options),
);
}
/**
* Enables support for hydrating i18n blocks.
*
* @publicApi 20.0
*/
export function withI18nSupport(): HydrationFeature<HydrationFeatureKind.I18nSupport> {
return hydrationFeature(HydrationFeatureKind.I18nSupport, ɵwithI18nSupport());
}
/**
* Enables support for replaying user events (e.g. `click`s) that happened on a page
* before hydration logic has completed. Once an application is hydrated, all captured
* events are replayed and relevant event listeners are executed.
*
* @usageNotes
*
* Basic example of how you can enable event replay in your application when
* `bootstrapApplication` function is used:
* ```ts
* bootstrapApplication(App, {
* providers: [provideClientHydration(withEventReplay())]
* });
* ```
* @publicApi
* @see {@link provideClientHydration}
*/
export function withEventReplay(): HydrationFeature<HydrationFeatureKind.EventReplay> {
return hydrationFeature(HydrationFeatureKind.EventReplay, ɵwithEventReplay());
}
/**
* Enables support for incremental hydration using the `hydrate` trigger syntax.
*
* @usageNotes
*
* Basic example of how you can enable incremental hydration in your application when
* the `bootstrapApplication` function is used:
* ```ts
* bootstrapApplication(App, {
* providers: [provideClientHydration(withIncrementalHydration())]
* });
* ```
* @publicApi 20.0
* @see {@link provideClientHydration}
*
* @deprecated Since v22.0.0, incremental hydration is enabled by default with `provideClientHydration`.
* Intent to remove in v24.
*/
export function withIncrementalHydration(): HydrationFeature<HydrationFeatureKind.IncrementalHydration> {
return hydrationFeature(HydrationFeatureKind.IncrementalHydration, ɵwithIncrementalHydration());
}
/**
* Disables support for incremental hydration (which is enabled by default).
*
* @publicApi 22.0
* @see {@link provideClientHydration}
*/
export function withNoIncrementalHydration(): HydrationFeature<HydrationFeatureKind.NoIncrementalHydration> {
return hydrationFeature(HydrationFeatureKind.NoIncrementalHydration);
}
/**
* Returns an `ENVIRONMENT_INITIALIZER` token setup with a function
* that verifies whether enabledBlocking initial navigation is used in an application
* and logs a warning in a console if it's not compatible with hydration.
*/
function provideEnabledBlockingInitialNavigationDetector(): Provider[] {
return [
{
provide: ENVIRONMENT_INITIALIZER,
useValue: () => {
const isEnabledBlockingInitialNavigation = inject(IS_ENABLED_BLOCKING_INITIAL_NAVIGATION, {
optional: true,
});
if (isEnabledBlockingInitialNavigation) {
const console = inject(Console);
const message = formatRuntimeError(
RuntimeErrorCode.HYDRATION_CONFLICTING_FEATURES,
'Configuration error: found both hydration and enabledBlocking initial navigation ' +
'in the same application, which is a contradiction.',
);
console.warn(message);
}
},
multi: true,
},
];
}
/**
* Sets up providers necessary to enable hydration functionality for the application.
*
* By default, the function enables the recommended set of features for the optimal
* performance for most of the applications. It includes the following features:
*
* * Reconciling DOM hydration. Learn more about it [here](guide/hydration).
* * [`HttpClient`](api/common/http/HttpClient) response caching while running on the server and
* transferring this cache to the client to avoid extra HTTP requests. Learn more about data caching
* [here](guide/ssr#caching-data-when-using-httpclient).
* Incremental hydration. [Learn more](guide/incremental-hydration).
*
* These functions allow you to disable some of the default features or enable new ones:
*
* * {@link withNoHttpTransferCache} to disable HTTP transfer cache
* * {@link withHttpTransferCacheOptions} to configure some HTTP transfer cache options
* * {@link withI18nSupport} to enable hydration support for i18n blocks
* * {@link withEventReplay} to enable support for replaying user events
* * {@link withNoIncrementalHydration} to disable incremental hydration
*
* @usageNotes
*
* Basic example of how you can enable hydration in your application when
* `bootstrapApplication` function is used:
* ```ts
* bootstrapApplication(App, {
* providers: [provideClientHydration()]
* });
* ```
*
* Alternatively if you are using NgModules, you would add `provideClientHydration`
* to your root app module's provider list.
* ```ts
* @NgModule({
* declarations: [RootCmp],
* bootstrap: [RootCmp],
* providers: [provideClientHydration()],
* })
* export class AppModule {}
* ```
*
* @see {@link withNoHttpTransferCache}
* @see {@link withHttpTransferCacheOptions}
* @see {@link withI18nSupport}
* @see {@link withEventReplay}
* @see {@link withNoIncrementalHydration}
*
* @param features Optional features to configure additional hydration behaviors.
* @returns A set of providers to enable hydration.
*
* @publicApi 17.0
*/
export function provideClientHydration(
...features: HydrationFeature<HydrationFeatureKind>[]
): EnvironmentProviders {
const providers: Provider[] = [];
const featuresKind = new Set<HydrationFeatureKind>();
for (const {ɵproviders, ɵkind} of features) {
featuresKind.add(ɵkind);
if (ɵproviders.length) {
providers.push(ɵproviders);
}
}
const hasHttpTransferCacheOptions = featuresKind.has(
HydrationFeatureKind.HttpTransferCacheOptions,
);
if (typeof ngDevMode !== 'undefined' && ngDevMode) {
if (featuresKind.has(HydrationFeatureKind.NoHttpTransferCache) && hasHttpTransferCacheOptions) {
throw new RuntimeError(
RuntimeErrorCode.HYDRATION_CONFLICTING_FEATURES,
'Configuration error: found both withHttpTransferCacheOptions() and withNoHttpTransferCache() in the same call to provideClientHydration(), which is a contradiction.',
);
}
if (
featuresKind.has(HydrationFeatureKind.IncrementalHydration) &&
featuresKind.has(HydrationFeatureKind.NoIncrementalHydration)
) {
throw new RuntimeError(
RuntimeErrorCode.HYDRATION_CONFLICTING_FEATURES,
'Configuration error: found both withIncrementalHydration() and withNoIncrementalHydration() in the same call to provideClientHydration(), which is a contradiction.',
);
}
}
return makeEnvironmentProviders([
typeof ngDevMode !== 'undefined' && ngDevMode
? provideEnabledBlockingInitialNavigationDetector()
: [],
typeof ngDevMode !== 'undefined' && ngDevMode ? provideStabilityDebugging() : [],
withDomHydration(),
featuresKind.has(HydrationFeatureKind.NoHttpTransferCache) || hasHttpTransferCacheOptions
? []
: ɵwithHttpTransferCache({}),
featuresKind.has(HydrationFeatureKind.NoIncrementalHydration)
? []
: ɵwithIncrementalHydration(),
providers,
{
provide: CACHE_ACTIVE,
useValue: {isActive: true},
},
{
provide: APP_BOOTSTRAP_LISTENER,
multi: true,
useFactory: () => {
const appRef = inject(ApplicationRef);
const cacheState = inject(CACHE_ACTIVE);
return () => {
appRef.whenStable().then(() => {
cacheState.isActive = false;
});
};
},
},
]);
}