@angular/ssr 18.2.1 → 19.0.0-next.1

package/esm2022/private_export.mjs

@@ -0,0 +1,10 @@
+/**
+ * @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
+ */
+export { getRoutesFromAngularRouterConfig as ɵgetRoutesFromAngularRouterConfig } from './src/routes/ng-routes';
+export { ServerRenderContext as ɵServerRenderContext, getOrCreateAngularServerApp as ɵgetOrCreateAngularServerApp, destroyAngularServerApp as ɵdestroyAngularServerApp, } from './src/app';
+export { setAngularAppManifest as ɵsetAngularAppManifest, setAngularAppEngineManifest as ɵsetAngularAppEngineManifest, } from './src/manifest';

package/esm2022/public_api.mjs

@@ -5,4 +5,5 @@
  * 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
  */
-export { CommonEngine, } from './src/common-engine';
+export { CommonEngine, } from './src/common-engine/common-engine';
+export * from './private_export';

package/esm2022/src/app-engine.mjs

@@ -0,0 +1,84 @@
+/**
+ * @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 { Hooks } from './hooks';
+import { getPotentialLocaleIdFromUrl } from './i18n';
+import { getAngularAppEngineManifest } from './manifest';
+/**
+ * Angular server application engine.
+ * Manages Angular server applications (including localized ones), handles rendering requests,
+ * and optionally transforms index HTML before rendering.
+ */
+export class AngularAppEngine {
+    /**
+     * Hooks for extending or modifying the behavior of the server application.
+     * These hooks are used by the Angular CLI when running the development server and
+     * provide extensibility points for the application lifecycle.
+     *
+     * @internal
+     */
+    static hooks = new Hooks();
+    /**
+     * Provides access to the hooks for extending or modifying the server application's behavior.
+     * This allows attaching custom functionality to various server application lifecycle events.
+     *
+     * @internal
+     */
+    get hooks() {
+        return AngularAppEngine.hooks;
+    }
+    /**
+     * The manifest for the server application.
+     */
+    manifest = getAngularAppEngineManifest();
+    /**
+     * Renders a response for the given HTTP request using the server application.
+     *
+     * This method processes the request, determines the appropriate route and rendering context,
+     * and returns an HTTP response.
+     *
+     * If the request URL appears to be for a file (excluding `/index.html`), the method returns `null`.
+     * A request to `https://www.example.com/page/index.html` will render the Angular route
+     * corresponding to `https://www.example.com/page`.
+     *
+     * @param request - The incoming HTTP request object to be rendered.
+     * @param requestContext - Optional additional context for the request, such as metadata.
+     * @returns A promise that resolves to a Response object, or `null` if the request URL represents a file (e.g., `./logo.png`)
+     * rather than an application route.
+     */
+    async render(request, requestContext) {
+        // Skip if the request looks like a file but not `/index.html`.
+        const url = new URL(request.url);
+        const entryPoint = this.getEntryPointFromUrl(url);
+        if (!entryPoint) {
+            return null;
+        }
+        const { ɵgetOrCreateAngularServerApp: getOrCreateAngularServerApp } = await entryPoint();
+        const serverApp = getOrCreateAngularServerApp();
+        serverApp.hooks = this.hooks;
+        return serverApp.render(request, requestContext);
+    }
+    /**
+     * Retrieves the entry point path and locale for the Angular server application based on the provided URL.
+     *
+     * This method determines the appropriate entry point and locale for rendering the application by examining the URL.
+     * If there is only one entry point available, it is returned regardless of the URL.
+     * Otherwise, the method extracts a potential locale identifier from the URL and looks up the corresponding entry point.
+     *
+     * @param url - The URL used to derive the locale and determine the appropriate entry point.
+     * @returns A function that returns a promise resolving to an object with the `EntryPointExports` type,
+     * or `undefined` if no matching entry point is found for the extracted locale.
+     */
+    getEntryPointFromUrl(url) {
+        const { entryPoints, basePath } = this.manifest;
+        if (entryPoints.size === 1) {
+            return entryPoints.values().next().value;
+        }
+        const potentialLocale = getPotentialLocaleIdFromUrl(url, basePath);
+        return entryPoints.get(potentialLocale);
+    }
+}

package/esm2022/src/app.mjs

@@ -0,0 +1,167 @@
+/**
+ * @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 { ɵConsole, ɵresetCompiledComponents } from '@angular/core';
+import { ɵSERVER_CONTEXT as SERVER_CONTEXT } from '@angular/platform-server';
+import { ServerAssets } from './assets';
+import { Console } from './console';
+import { Hooks } from './hooks';
+import { getAngularAppManifest } from './manifest';
+import { ServerRouter } from './routes/router';
+import { REQUEST, REQUEST_CONTEXT, RESPONSE_INIT } from './tokens';
+import { renderAngular } from './utils/ng';
+/**
+ * Enum representing the different contexts in which server rendering can occur.
+ */
+export var ServerRenderContext;
+(function (ServerRenderContext) {
+    ServerRenderContext["SSR"] = "ssr";
+    ServerRenderContext["SSG"] = "ssg";
+    ServerRenderContext["AppShell"] = "app-shell";
+})(ServerRenderContext || (ServerRenderContext = {}));
+/**
+ * Represents a locale-specific Angular server application managed by the server application engine.
+ *
+ * The `AngularServerApp` class handles server-side rendering and asset management for a specific locale.
+ */
+export class AngularServerApp {
+    /**
+     * Hooks for extending or modifying the behavior of the server application.
+     * This instance can be used to attach custom functionality to various events in the server application lifecycle.
+     */
+    hooks = new Hooks();
+    /**
+     * The manifest associated with this server application.
+     */
+    manifest = getAngularAppManifest();
+    /**
+     * An instance of ServerAsset that handles server-side asset.
+     */
+    assets = new ServerAssets(this.manifest);
+    /**
+     * The router instance used for route matching and handling.
+     */
+    router;
+    /**
+     * Renders a response for the given HTTP request using the server application.
+     *
+     * This method processes the request and returns a response based on the specified rendering context.
+     *
+     * @param request - The incoming HTTP request to be rendered.
+     * @param requestContext - Optional additional context for rendering, such as request metadata.
+     * @param serverContext - The rendering context.
+     *
+     * @returns A promise that resolves to the HTTP response object resulting from the rendering, or null if no match is found.
+     */
+    render(request, requestContext, serverContext = ServerRenderContext.SSR) {
+        return Promise.race([
+            this.createAbortPromise(request),
+            this.handleRendering(request, requestContext, serverContext),
+        ]);
+    }
+    /**
+     * Creates a promise that rejects when the request is aborted.
+     *
+     * @param request - The HTTP request to monitor for abortion.
+     * @returns A promise that never resolves but rejects with an `AbortError` if the request is aborted.
+     */
+    createAbortPromise(request) {
+        return new Promise((_, reject) => {
+            request.signal.addEventListener('abort', () => {
+                const abortError = new Error(`Request for: ${request.url} was aborted.\n${request.signal.reason}`);
+                abortError.name = 'AbortError';
+                reject(abortError);
+            }, { once: true });
+        });
+    }
+    /**
+     * Handles the server-side rendering process for the given HTTP request.
+     * This method matches the request URL to a route and performs rendering if a matching route is found.
+     *
+     * @param request - The incoming HTTP request to be processed.
+     * @param requestContext - Optional additional context for rendering, such as request metadata.
+     * @param serverContext - The rendering context. Defaults to server-side rendering (SSR).
+     *
+     * @returns A promise that resolves to the rendered response, or null if no matching route is found.
+     */
+    async handleRendering(request, requestContext, serverContext = ServerRenderContext.SSR) {
+        const url = new URL(request.url);
+        this.router ??= await ServerRouter.from(this.manifest, url);
+        const matchedRoute = this.router.match(url);
+        if (!matchedRoute) {
+            // Not a known Angular route.
+            return null;
+        }
+        const { redirectTo } = matchedRoute;
+        if (redirectTo !== undefined) {
+            // 302 Found is used by default for redirections
+            // See: https://developer.mozilla.org/en-US/docs/Web/API/Response/redirect_static#status
+            return Response.redirect(new URL(redirectTo, url), 302);
+        }
+        const platformProviders = [
+            {
+                provide: SERVER_CONTEXT,
+                useValue: serverContext,
+            },
+            {
+                // An Angular Console Provider that does not print a set of predefined logs.
+                provide: ɵConsole,
+                // Using `useClass` would necessitate decorating `Console` with `@Injectable`,
+                // which would require switching from `ts_library` to `ng_module`. This change
+                // would also necessitate various patches of `@angular/bazel` to support ESM.
+                useFactory: () => new Console(),
+            },
+        ];
+        const isSsrMode = serverContext === ServerRenderContext.SSR;
+        const responseInit = {};
+        if (isSsrMode) {
+            platformProviders.push({
+                provide: REQUEST,
+                useValue: request,
+            }, {
+                provide: REQUEST_CONTEXT,
+                useValue: requestContext,
+            }, {
+                provide: RESPONSE_INIT,
+                useValue: responseInit,
+            });
+        }
+        if (typeof ngDevMode === 'undefined' || ngDevMode) {
+            // Need to clean up GENERATED_COMP_IDS map in `@angular/core`.
+            // Otherwise an incorrect component ID generation collision detected warning will be displayed in development.
+            // See: https://github.com/angular/angular-cli/issues/25924
+            ɵresetCompiledComponents();
+        }
+        const { manifest, hooks, assets } = this;
+        let html = await assets.getIndexServerHtml();
+        // Skip extra microtask if there are no pre hooks.
+        if (hooks.has('html:transform:pre')) {
+            html = await hooks.run('html:transform:pre', { html });
+        }
+        return new Response(await renderAngular(html, manifest.bootstrap(), new URL(request.url), platformProviders), responseInit);
+    }
+}
+let angularServerApp;
+/**
+ * Retrieves or creates an instance of `AngularServerApp`.
+ * - If an instance of `AngularServerApp` already exists, it will return the existing one.
+ * - If no instance exists, it will create a new one with the provided options.
+ * @returns The existing or newly created instance of `AngularServerApp`.
+ */
+export function getOrCreateAngularServerApp() {
+    return (angularServerApp ??= new AngularServerApp());
+}
+/**
+ * Destroys the existing `AngularServerApp` instance, releasing associated resources and resetting the
+ * reference to `undefined`.
+ *
+ * This function is primarily used to enable the recreation of the `AngularServerApp` instance,
+ * typically when server configuration or application state needs to be refreshed.
+ */
+export function destroyAngularServerApp() {
+    angularServerApp = undefined;
+}

package/esm2022/src/assets.mjs

@@ -0,0 +1,44 @@
+/**
+ * @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
+ */
+/**
+ * Manages server-side assets.
+ */
+export class ServerAssets {
+    manifest;
+    /**
+     * Creates an instance of ServerAsset.
+     *
+     * @param manifest - The manifest containing the server assets.
+     */
+    constructor(manifest) {
+        this.manifest = manifest;
+    }
+    /**
+     * Retrieves the content of a server-side asset using its path.
+     *
+     * @param path - The path to the server asset.
+     * @returns A promise that resolves to the asset content as a string.
+     * @throws Error If the asset path is not found in the manifest, an error is thrown.
+     */
+    async getServerAsset(path) {
+        const asset = this.manifest.assets.get(path);
+        if (!asset) {
+            throw new Error(`Server asset '${path}' does not exist.`);
+        }
+        return asset();
+    }
+    /**
+     * Retrieves and caches the content of 'index.server.html'.
+     *
+     * @returns A promise that resolves to the content of 'index.server.html'.
+     * @throws Error If there is an issue retrieving the asset.
+     */
+    getIndexServerHtml() {
+        return this.getServerAsset('index.server.html');
+    }
+}

package/esm2022/src/console.mjs

@@ -0,0 +1,34 @@
+/**
+ * @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 { ɵConsole } from '@angular/core';
+/**
+ * Custom implementation of the Angular Console service that filters out specific log messages.
+ *
+ * This class extends the internal Angular `ɵConsole` class to provide customized logging behavior.
+ * It overrides the `log` method to suppress logs that match certain predefined messages.
+ */
+export class Console extends ɵConsole {
+    /**
+     * A set of log messages that should be ignored and not printed to the console.
+     */
+    ignoredLogs = new Set(['Angular is running in development mode.']);
+    /**
+     * Logs a message to the console if it is not in the set of ignored messages.
+     *
+     * @param message - The message to log to the console.
+     *
+     * This method overrides the `log` method of the `ɵConsole` class. It checks if the
+     * message is in the `ignoredLogs` set. If it is not, it delegates the logging to
+     * the parent class's `log` method. Otherwise, the message is suppressed.
+     */
+    log(message) {
+        if (!this.ignoredLogs.has(message)) {
+            super.log(message);
+        }
+    }
+}

package/esm2022/src/hooks.mjs

@@ -0,0 +1,94 @@
+/**
+ * @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
+ */
+/**
+ * Manages a collection of hooks and provides methods to register and execute them.
+ * Hooks are functions that can be invoked with specific arguments to allow modifications or enhancements.
+ */
+export class Hooks {
+    /**
+     * A map of hook names to arrays of hook functions.
+     * Each hook name can have multiple associated functions, which are executed in sequence.
+     */
+    store = new Map();
+    /**
+     * Executes all hooks associated with the specified name, passing the given argument to each hook function.
+     * The hooks are invoked sequentially, and the argument may be modified by each hook.
+     *
+     * @template Hook - The type of the hook name. It should be one of the keys of `HooksMapping`.
+     * @param name - The name of the hook whose functions will be executed.
+     * @param context - The input value to be passed to each hook function. The value is mutated by each hook function.
+     * @returns A promise that resolves once all hook functions have been executed.
+     *
+     * @example
+     * ```typescript
+     * const hooks = new Hooks();
+     * hooks.on('html:transform:pre', async (ctx) => {
+     *   ctx.html = ctx.html.replace(/foo/g, 'bar');
+     *   return ctx.html;
+     * });
+     * const result = await hooks.run('html:transform:pre', { html: '<div>foo</div>' });
+     * console.log(result); // '<div>bar</div>'
+     * ```
+     * @internal
+     */
+    async run(name, context) {
+        const hooks = this.store.get(name);
+        switch (name) {
+            case 'html:transform:pre': {
+                if (!hooks) {
+                    return context.html;
+                }
+                const ctx = { ...context };
+                for (const hook of hooks) {
+                    ctx.html = await hook(ctx);
+                }
+                return ctx.html;
+            }
+            default:
+                throw new Error(`Running hook "${name}" is not supported.`);
+        }
+    }
+    /**
+     * Registers a new hook function under the specified hook name.
+     * This function should be a function that takes an argument of type `T` and returns a `string` or `Promise<string>`.
+     *
+     * @template Hook - The type of the hook name. It should be one of the keys of `HooksMapping`.
+     * @param name - The name of the hook under which the function will be registered.
+     * @param handler - A function to be executed when the hook is triggered. The handler will be called with an argument
+     *                  that may be modified by the hook functions.
+     *
+     * @remarks
+     * - If there are existing handlers registered under the given hook name, the new handler will be added to the list.
+     * - If no handlers are registered under the given hook name, a new list will be created with the handler as its first element.
+     *
+     * @example
+     * ```typescript
+     * hooks.on('html:transform:pre', async (ctx) => {
+     *   return ctx.html.replace(/foo/g, 'bar');
+     * });
+     * ```
+     */
+    on(name, handler) {
+        const hooks = this.store.get(name);
+        if (hooks) {
+            hooks.push(handler);
+        }
+        else {
+            this.store.set(name, [handler]);
+        }
+    }
+    /**
+     * Checks if there are any hooks registered under the specified name.
+     *
+     * @param name - The name of the hook to check.
+     * @returns `true` if there are hooks registered under the specified name, otherwise `false`.
+     */
+    has(name) {
+        return !!this.store.get(name)?.length;
+    }
+}

package/esm2022/src/i18n.mjs

@@ -0,0 +1,41 @@
+/**
+ * @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
+ */
+/**
+ * Extracts a potential locale ID from a given URL based on the specified base path.
+ *
+ * This function parses the URL to locate a potential locale identifier that immediately
+ * follows the base path segment in the URL's pathname. If the URL does not contain a valid
+ * locale ID, an empty string is returned.
+ *
+ * @param url - The full URL from which to extract the locale ID.
+ * @param basePath - The base path used as the reference point for extracting the locale ID.
+ * @returns The extracted locale ID if present, or an empty string if no valid locale ID is found.
+ *
+ * @example
+ * ```js
+ * const url = new URL('https://example.com/base/en/page');
+ * const basePath = '/base';
+ * const localeId = getPotentialLocaleIdFromUrl(url, basePath);
+ * console.log(localeId); // Output: 'en'
+ * ```
+ */
+export function getPotentialLocaleIdFromUrl(url, basePath) {
+    const { pathname } = url;
+    // Move forward of the base path section.
+    let start = basePath.length;
+    if (pathname[start] === '/') {
+        start++;
+    }
+    // Find the next forward slash.
+    let end = pathname.indexOf('/', start);
+    if (end === -1) {
+        end = pathname.length;
+    }
+    // Extract the potential locale id.
+    return pathname.slice(start, end);
+}

package/esm2022/src/manifest.mjs

@@ -0,0 +1,59 @@
+/**
+ * @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
+ */
+/**
+ * The Angular app manifest object.
+ * This is used internally to store the current Angular app manifest.
+ */
+let angularAppManifest;
+/**
+ * Sets the Angular app manifest.
+ *
+ * @param manifest - The manifest object to set for the Angular application.
+ */
+export function setAngularAppManifest(manifest) {
+    angularAppManifest = manifest;
+}
+/**
+ * Gets the Angular app manifest.
+ *
+ * @returns The Angular app manifest.
+ * @throws Will throw an error if the Angular app manifest is not set.
+ */
+export function getAngularAppManifest() {
+    if (!angularAppManifest) {
+        throw new Error('Angular app manifest is not set. ' +
+            `Please ensure you are using the '@angular/build:application' builder to build your server application.`);
+    }
+    return angularAppManifest;
+}
+/**
+ * The Angular app engine manifest object.
+ * This is used internally to store the current Angular app engine manifest.
+ */
+let angularAppEngineManifest;
+/**
+ * Sets the Angular app engine manifest.
+ *
+ * @param manifest - The engine manifest object to set.
+ */
+export function setAngularAppEngineManifest(manifest) {
+    angularAppEngineManifest = manifest;
+}
+/**
+ * Gets the Angular app engine manifest.
+ *
+ * @returns The Angular app engine manifest.
+ * @throws Will throw an error if the Angular app engine manifest is not set.
+ */
+export function getAngularAppEngineManifest() {
+    if (!angularAppEngineManifest) {
+        throw new Error('Angular app engine manifest is not set. ' +
+            `Please ensure you are using the '@angular/build:application' builder to build your server application.`);
+    }
+    return angularAppEngineManifest;
+}

package/esm2022/src/request.mjs

@@ -0,0 +1,63 @@
+/**
+ * @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
+ */
+/**
+ * Converts a Node.js `IncomingMessage` into a Web Standard `Request`.
+ *
+ * @param nodeRequest - The Node.js `IncomingMessage` object to convert.
+ * @returns A Web Standard `Request` object.
+ */
+export function createWebRequestFromNodeRequest(nodeRequest) {
+    const { headers, method = 'GET' } = nodeRequest;
+    const withBody = method !== 'GET' && method !== 'HEAD';
+    return new Request(createRequestUrl(nodeRequest), {
+        method,
+        headers: createRequestHeaders(headers),
+        body: withBody ? nodeRequest : undefined,
+        duplex: withBody ? 'half' : undefined,
+    });
+}
+/**
+ * Creates a `Headers` object from Node.js `IncomingHttpHeaders`.
+ *
+ * @param nodeHeaders - The Node.js `IncomingHttpHeaders` object to convert.
+ * @returns A `Headers` object containing the converted headers.
+ */
+function createRequestHeaders(nodeHeaders) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(nodeHeaders)) {
+        if (typeof value === 'string') {
+            headers.append(name, value);
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                headers.append(name, item);
+            }
+        }
+    }
+    return headers;
+}
+/**
+ * Creates a `URL` object from a Node.js `IncomingMessage`, taking into account the protocol, host, and port.
+ *
+ * @param nodeRequest - The Node.js `IncomingMessage` object to extract URL information from.
+ * @returns A `URL` object representing the request URL.
+ */
+function createRequestUrl(nodeRequest) {
+    const { headers, socket, url = '' } = nodeRequest;
+    const protocol = headers['x-forwarded-proto'] ?? ('encrypted' in socket && socket.encrypted ? 'https' : 'http');
+    const hostname = headers['x-forwarded-host'] ?? headers.host ?? headers[':authority'];
+    const port = headers['x-forwarded-port'] ?? socket.localPort;
+    if (Array.isArray(hostname)) {
+        throw new Error('host value cannot be an array.');
+    }
+    let hostnameWithPort = hostname;
+    if (port && !hostname?.includes(':')) {
+        hostnameWithPort += `:${port}`;
+    }
+    return new URL(url, `${protocol}://${hostnameWithPort}`);
+}

package/esm2022/src/response.mjs

@@ -0,0 +1,58 @@
+/**
+ * @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
+ */
+/**
+ * Streams a web-standard `Response` into a Node.js `ServerResponse`.
+ *
+ * @param source - The web-standard `Response` object to stream from.
+ * @param destination - The Node.js `ServerResponse` object to stream into.
+ * @returns A promise that resolves once the streaming operation is complete.
+ */
+export async function writeResponseToNodeResponse(source, destination) {
+    const { status, headers, body } = source;
+    destination.statusCode = status;
+    let cookieHeaderSet = false;
+    for (const [name, value] of headers.entries()) {
+        if (name === 'set-cookie') {
+            if (cookieHeaderSet) {
+                continue;
+            }
+            // Sets the 'set-cookie' header only once to ensure it is correctly applied.
+            // Concatenating 'set-cookie' values can lead to incorrect behavior, so we use a single value from `headers.getSetCookie()`.
+            destination.setHeader(name, headers.getSetCookie());
+            cookieHeaderSet = true;
+        }
+        else {
+            destination.setHeader(name, value);
+        }
+    }
+    if (!body) {
+        destination.end();
+        return;
+    }
+    try {
+        const reader = body.getReader();
+        destination.on('close', () => {
+            reader.cancel().catch((error) => {
+                // eslint-disable-next-line no-console
+                console.error(`An error occurred while writing the response body for: ${destination.req.url}.`, error);
+            });
+        });
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                destination.end();
+                break;
+            }
+            destination.write(value);
+        }
+    }
+    catch {
+        destination.end('Internal server error.');
+    }
+}