@angular/ssr 18.2.1 → 19.0.0-next.1

package/esm2022/src/routes/ng-routes.mjs

@@ -0,0 +1,157 @@
+/**
+ * @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 { APP_BASE_HREF, PlatformLocation } from '@angular/common';
+import { ApplicationRef, Compiler, createPlatformFactory, platformCore, ɵwhenStable as whenStable, ɵConsole, ɵresetCompiledComponents, } from '@angular/core';
+import { INITIAL_CONFIG, ɵINTERNAL_SERVER_PLATFORM_PROVIDERS as INTERNAL_SERVER_PLATFORM_PROVIDERS, } from '@angular/platform-server';
+import { Router, ɵloadChildren as loadChildrenHelper } from '@angular/router';
+import { Console } from '../console';
+import { isNgModule } from '../utils/ng';
+import { joinUrlParts } from '../utils/url';
+/**
+ * Recursively traverses the Angular router configuration to retrieve routes.
+ *
+ * Iterates through the router configuration, yielding each route along with its potential
+ * redirection or error status. Handles nested routes and lazy-loaded child routes.
+ *
+ * @param options - An object containing the parameters for traversing routes.
+ * @returns An async iterator yielding `RouteResult` objects.
+ */
+async function* traverseRoutesConfig(options) {
+    const { routes, compiler, parentInjector, parentRoute } = options;
+    for (const route of routes) {
+        const { path = '', redirectTo, loadChildren, children } = route;
+        const currentRoutePath = joinUrlParts(parentRoute, path);
+        yield {
+            route: currentRoutePath,
+            redirectTo: typeof redirectTo === 'string'
+                ? resolveRedirectTo(currentRoutePath, redirectTo)
+                : undefined,
+        };
+        if (children?.length) {
+            // Recursively process child routes.
+            yield* traverseRoutesConfig({
+                routes: children,
+                compiler,
+                parentInjector,
+                parentRoute: currentRoutePath,
+            });
+        }
+        if (loadChildren) {
+            // Load and process lazy-loaded child routes.
+            const loadedChildRoutes = await loadChildrenHelper(route, compiler, parentInjector).toPromise();
+            if (loadedChildRoutes) {
+                const { routes: childRoutes, injector = parentInjector } = loadedChildRoutes;
+                yield* traverseRoutesConfig({
+                    routes: childRoutes,
+                    compiler,
+                    parentInjector: injector,
+                    parentRoute: currentRoutePath,
+                });
+            }
+        }
+    }
+}
+/**
+ * Resolves the `redirectTo` property for a given route.
+ *
+ * This function processes the `redirectTo` property to ensure that it correctly
+ * resolves relative to the current route path. If `redirectTo` is an absolute path,
+ * it is returned as is. If it is a relative path, it is resolved based on the current route path.
+ *
+ * @param routePath - The current route path.
+ * @param redirectTo - The target path for redirection.
+ * @returns The resolved redirect path as a string.
+ */
+function resolveRedirectTo(routePath, redirectTo) {
+    if (redirectTo[0] === '/') {
+        // If the redirectTo path is absolute, return it as is.
+        return redirectTo;
+    }
+    // Resolve relative redirectTo based on the current route path.
+    const segments = routePath.split('/');
+    segments.pop(); // Remove the last segment to make it relative.
+    return joinUrlParts(...segments, redirectTo);
+}
+/**
+ * Retrieves routes from the given Angular application.
+ *
+ * This function initializes an Angular platform, bootstraps the application or module,
+ * and retrieves routes from the Angular router configuration. It handles both module-based
+ * and function-based bootstrapping. It yields the resulting routes as `RouteResult` objects.
+ *
+ * @param bootstrap - A function that returns a promise resolving to an `ApplicationRef` or an Angular module to bootstrap.
+ * @param document - The initial HTML document used for server-side rendering.
+ * This document is necessary to render the application on the server.
+ * @param url - The URL for server-side rendering. The URL is used to configure `ServerPlatformLocation`. This configuration is crucial
+ * for ensuring that API requests for relative paths succeed, which is essential for accurate route extraction.
+ * See:
+ *  - https://github.com/angular/angular/blob/d608b857c689d17a7ffa33bbb510301014d24a17/packages/platform-server/src/location.ts#L51
+ *  - https://github.com/angular/angular/blob/6882cc7d9eed26d3caeedca027452367ba25f2b9/packages/platform-server/src/http.ts#L44
+ * @returns A promise that resolves to an object of type `AngularRouterConfigResult`.
+ */
+export async function getRoutesFromAngularRouterConfig(bootstrap, document, url) {
+    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 { protocol, host } = url;
+    // Create and initialize the Angular platform for server-side rendering.
+    const platformRef = createPlatformFactory(platformCore, 'server', [
+        {
+            provide: INITIAL_CONFIG,
+            useValue: { document, url: `${protocol}//${host}/` },
+        },
+        {
+            provide: ɵConsole,
+            useFactory: () => new Console(),
+        },
+        ...INTERNAL_SERVER_PLATFORM_PROVIDERS,
+    ])();
+    try {
+        let applicationRef;
+        if (isNgModule(bootstrap)) {
+            const moduleRef = await platformRef.bootstrapModule(bootstrap);
+            applicationRef = moduleRef.injector.get(ApplicationRef);
+        }
+        else {
+            applicationRef = await bootstrap();
+        }
+        // Wait until the application is stable.
+        await whenStable(applicationRef);
+        const injector = applicationRef.injector;
+        const router = injector.get(Router);
+        const routesResults = [];
+        if (router.config.length) {
+            const compiler = injector.get(Compiler);
+            // Retrieve all routes from the Angular router configuration.
+            const traverseRoutes = traverseRoutesConfig({
+                routes: router.config,
+                compiler,
+                parentInjector: injector,
+                parentRoute: '',
+            });
+            for await (const result of traverseRoutes) {
+                routesResults.push(result);
+            }
+        }
+        else {
+            routesResults.push({ route: '' });
+        }
+        const baseHref = injector.get(APP_BASE_HREF, null, { optional: true }) ??
+            injector.get(PlatformLocation).getBaseHrefFromDOM();
+        return {
+            baseHref,
+            routes: routesResults,
+        };
+    }
+    finally {
+        platformRef.destroy();
+    }
+}

package/esm2022/src/routes/route-tree.mjs

@@ -0,0 +1,180 @@
+/**
+ * @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 { stripTrailingSlash } from '../utils/url';
+/**
+ * A route tree implementation that supports efficient route matching, including support for wildcard routes.
+ * This structure is useful for organizing and retrieving routes in a hierarchical manner,
+ * enabling complex routing scenarios with nested paths.
+ */
+export class RouteTree {
+    /**
+     * The root node of the route tree.
+     * All routes are stored and accessed relative to this root node.
+     */
+    root = this.createEmptyRouteTreeNode('');
+    /**
+     * A counter that tracks the order of route insertion.
+     * This ensures that routes are matched in the order they were defined,
+     * with earlier routes taking precedence.
+     */
+    insertionIndexCounter = 0;
+    /**
+     * Inserts a new route into the route tree.
+     * The route is broken down into segments, and each segment is added to the tree.
+     * Parameterized segments (e.g., :id) are normalized to wildcards (*) for matching purposes.
+     *
+     * @param route - The route path to insert into the tree.
+     * @param metadata - Metadata associated with the route, excluding the route path itself.
+     */
+    insert(route, metadata) {
+        let node = this.root;
+        const normalizedRoute = stripTrailingSlash(route);
+        const segments = normalizedRoute.split('/');
+        for (const segment of segments) {
+            // Replace parameterized segments (e.g., :id) with a wildcard (*) for matching
+            const normalizedSegment = segment[0] === ':' ? '*' : segment;
+            let childNode = node.children.get(normalizedSegment);
+            if (!childNode) {
+                childNode = this.createEmptyRouteTreeNode(normalizedSegment);
+                node.children.set(normalizedSegment, childNode);
+            }
+            node = childNode;
+        }
+        // At the leaf node, store the full route and its associated metadata
+        node.metadata = {
+            ...metadata,
+            route: normalizedRoute,
+        };
+        node.insertionIndex = this.insertionIndexCounter++;
+    }
+    /**
+     * Matches a given route against the route tree and returns the best matching route's metadata.
+     * The best match is determined by the lowest insertion index, meaning the earliest defined route
+     * takes precedence.
+     *
+     * @param route - The route path to match against the route tree.
+     * @returns The metadata of the best matching route or `undefined` if no match is found.
+     */
+    match(route) {
+        const segments = stripTrailingSlash(route).split('/');
+        return this.traverseBySegments(segments)?.metadata;
+    }
+    /**
+     * Converts the route tree into a serialized format representation.
+     * This method converts the route tree into an array of metadata objects that describe the structure of the tree.
+     * The array represents the routes in a nested manner where each entry includes the route and its associated metadata.
+     *
+     * @returns An array of `RouteTreeNodeMetadata` objects representing the route tree structure.
+     *          Each object includes the `route` and associated metadata of a route.
+     */
+    toObject() {
+        return Array.from(this.traverse());
+    }
+    /**
+     * Constructs a `RouteTree` from an object representation.
+     * This method is used to recreate a `RouteTree` instance from an array of metadata objects.
+     * The array should be in the format produced by `toObject`, allowing for the reconstruction of the route tree
+     * with the same routes and metadata.
+     *
+     * @param value - An array of `RouteTreeNodeMetadata` objects that represent the serialized format of the route tree.
+     *                Each object should include a `route` and its associated metadata.
+     * @returns A new `RouteTree` instance constructed from the provided metadata objects.
+     */
+    static fromObject(value) {
+        const tree = new RouteTree();
+        for (const { route, ...metadata } of value) {
+            tree.insert(route, metadata);
+        }
+        return tree;
+    }
+    /**
+     * A generator function that recursively traverses the route tree and yields the metadata of each node.
+     * This allows for easy and efficient iteration over all nodes in the tree.
+     *
+     * @param node - The current node to start the traversal from. Defaults to the root node of the tree.
+     */
+    *traverse(node = this.root) {
+        if (node.metadata) {
+            yield node.metadata;
+        }
+        for (const childNode of node.children.values()) {
+            yield* this.traverse(childNode);
+        }
+    }
+    /**
+     * Recursively traverses the route tree from a given node, attempting to match the remaining route segments.
+     * If the node is a leaf node (no more segments to match) and contains metadata, the node is yielded.
+     *
+     * This function prioritizes exact segment matches first, followed by wildcard matches (`*`),
+     * and finally deep wildcard matches (`**`) that consume all segments.
+     *
+     * @param remainingSegments - The remaining segments of the route path to match.
+     * @param node - The current node in the route tree to start traversal from.
+     *
+     * @returns The node that best matches the remaining segments or `undefined` if no match is found.
+     */
+    traverseBySegments(remainingSegments, node = this.root) {
+        const { metadata, children } = node;
+        // If there are no remaining segments and the node has metadata, return this node
+        if (!remainingSegments?.length) {
+            if (metadata) {
+                return node;
+            }
+            return;
+        }
+        // If the node has no children, end the traversal
+        if (!children.size) {
+            return;
+        }
+        const [segment, ...restSegments] = remainingSegments;
+        let currentBestMatchNode;
+        // 1. Exact segment match
+        const exactMatchNode = node.children.get(segment);
+        currentBestMatchNode = this.getHigherPriorityNode(currentBestMatchNode, this.traverseBySegments(restSegments, exactMatchNode));
+        // 2. Wildcard segment match (`*`)
+        const wildcardNode = node.children.get('*');
+        currentBestMatchNode = this.getHigherPriorityNode(currentBestMatchNode, this.traverseBySegments(restSegments, wildcardNode));
+        // 3. Deep wildcard segment match (`**`)
+        const deepWildcardNode = node.children.get('**');
+        currentBestMatchNode = this.getHigherPriorityNode(currentBestMatchNode, deepWildcardNode);
+        return currentBestMatchNode;
+    }
+    /**
+     * Compares two nodes and returns the node with higher priority based on insertion index.
+     * A node with a lower insertion index is prioritized as it was defined earlier.
+     *
+     * @param currentBestMatchNode - The current best match node.
+     * @param candidateNode - The node being evaluated for higher priority based on insertion index.
+     * @returns The node with higher priority (i.e., lower insertion index). If one of the nodes is `undefined`, the other node is returned.
+     */
+    getHigherPriorityNode(currentBestMatchNode, candidateNode) {
+        if (!candidateNode) {
+            return currentBestMatchNode;
+        }
+        if (!currentBestMatchNode) {
+            return candidateNode;
+        }
+        return candidateNode.insertionIndex < currentBestMatchNode.insertionIndex
+            ? candidateNode
+            : currentBestMatchNode;
+    }
+    /**
+     * Creates an empty route tree node with the specified segment.
+     * This helper function is used during the tree construction.
+     *
+     * @param segment - The route segment that this node represents.
+     * @returns A new, empty route tree node.
+     */
+    createEmptyRouteTreeNode(segment) {
+        return {
+            segment,
+            insertionIndex: -1,
+            children: new Map(),
+        };
+    }
+}

package/esm2022/src/routes/router.mjs

@@ -0,0 +1,88 @@
+/**
+ * @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 { ServerAssets } from '../assets';
+import { joinUrlParts, stripIndexHtmlFromURL } from '../utils/url';
+import { getRoutesFromAngularRouterConfig } from './ng-routes';
+import { RouteTree } from './route-tree';
+/**
+ * Manages the application's server routing logic by building and maintaining a route tree.
+ *
+ * This class is responsible for constructing the route tree from the Angular application
+ * configuration and using it to match incoming requests to the appropriate routes.
+ */
+export class ServerRouter {
+    routeTree;
+    /**
+     * Creates an instance of the `ServerRouter`.
+     *
+     * @param routeTree - An instance of `RouteTree` that holds the routing information.
+     * The `RouteTree` is used to match request URLs to the appropriate route metadata.
+     */
+    constructor(routeTree) {
+        this.routeTree = routeTree;
+    }
+    /**
+     * Static property to track the ongoing build promise.
+     */
+    static #extractionPromise;
+    /**
+     * Creates or retrieves a `ServerRouter` instance based on the provided manifest and URL.
+     *
+     * If the manifest contains pre-built routes, a new `ServerRouter` is immediately created.
+     * Otherwise, it builds the router by extracting routes from the Angular configuration
+     * asynchronously. This method ensures that concurrent builds are prevented by re-using
+     * the same promise.
+     *
+     * @param manifest - An instance of `AngularAppManifest` that contains the route information.
+     * @param url - The URL for server-side rendering. The URL is needed to configure `ServerPlatformLocation`.
+     * This is necessary to ensure that API requests for relative paths succeed, which is crucial for correct route extraction.
+     * [Reference](https://github.com/angular/angular/blob/d608b857c689d17a7ffa33bbb510301014d24a17/packages/platform-server/src/location.ts#L51)
+     * @returns A promise resolving to a `ServerRouter` instance.
+     */
+    static from(manifest, url) {
+        if (manifest.routes) {
+            const routeTree = RouteTree.fromObject(manifest.routes);
+            return Promise.resolve(new ServerRouter(routeTree));
+        }
+        // Create and store a new promise for the build process.
+        // This prevents concurrent builds by re-using the same promise.
+        ServerRouter.#extractionPromise ??= (async () => {
+            try {
+                const routeTree = new RouteTree();
+                const document = await new ServerAssets(manifest).getIndexServerHtml();
+                const { baseHref, routes } = await getRoutesFromAngularRouterConfig(manifest.bootstrap(), document, url);
+                for (let { route, redirectTo } of routes) {
+                    route = joinUrlParts(baseHref, route);
+                    redirectTo = redirectTo === undefined ? undefined : joinUrlParts(baseHref, redirectTo);
+                    routeTree.insert(route, { redirectTo });
+                }
+                return new ServerRouter(routeTree);
+            }
+            finally {
+                ServerRouter.#extractionPromise = undefined;
+            }
+        })();
+        return ServerRouter.#extractionPromise;
+    }
+    /**
+     * Matches a request URL against the route tree to retrieve route metadata.
+     *
+     * This method strips 'index.html' from the URL if it is present and then attempts
+     * to find a match in the route tree. If a match is found, it returns the associated
+     * route metadata; otherwise, it returns `undefined`.
+     *
+     * @param url - The URL to be matched against the route tree.
+     * @returns The metadata for the matched route or `undefined` if no match is found.
+     */
+    match(url) {
+        // Strip 'index.html' from URL if present.
+        // A request to `http://www.example.com/page/index.html` will render the Angular route corresponding to `http://www.example.com/page`.
+        const { pathname } = stripIndexHtmlFromURL(url);
+        return this.routeTree.match(decodeURIComponent(pathname));
+    }
+}

package/esm2022/src/tokens.mjs

@@ -0,0 +1,20 @@
+/**
+ * @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 { InjectionToken } from '@angular/core';
+/**
+ * Injection token for the current request.
+ */
+export const REQUEST = new InjectionToken('REQUEST');
+/**
+ * Injection token for the response initialization options.
+ */
+export const RESPONSE_INIT = new InjectionToken('RESPONSE_INIT');
+/**
+ * Injection token for additional request context.
+ */
+export const REQUEST_CONTEXT = new InjectionToken('REQUEST_CONTEXT');

package/esm2022/src/utils/ng.mjs

@@ -0,0 +1,51 @@
+/**
+ * @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 { renderApplication, renderModule } from '@angular/platform-server';
+import { stripIndexHtmlFromURL } from './url';
+/**
+ * Renders an Angular application or module to an HTML string.
+ *
+ * This function determines whether the provided `bootstrap` value is an Angular module
+ * or a bootstrap function and calls the appropriate rendering method (`renderModule` or
+ * `renderApplication`) based on that determination.
+ *
+ * @param html - The HTML string to be used as the initial document content.
+ * @param bootstrap - Either an Angular module type or a function that returns a promise
+ *                    resolving to an `ApplicationRef`.
+ * @param url - The URL of the application. This is used for server-side rendering to
+ *              correctly handle route-based rendering.
+ * @param platformProviders - An array of platform providers to be used during the
+ *                             rendering process.
+ * @returns A promise that resolves to a string containing the rendered HTML.
+ */
+export function renderAngular(html, bootstrap, url, platformProviders) {
+    // A request to `http://www.example.com/page/index.html` will render the Angular route corresponding to `http://www.example.com/page`.
+    const urlToRender = stripIndexHtmlFromURL(url).toString();
+    return isNgModule(bootstrap)
+        ? renderModule(bootstrap, {
+            url: urlToRender,
+            document: html,
+            extraProviders: platformProviders,
+        })
+        : renderApplication(bootstrap, {
+            url: urlToRender,
+            document: html,
+            platformProviders,
+        });
+}
+/**
+ * Type guard to determine if a given value is an Angular module.
+ * Angular modules are identified by the presence of the `ɵmod` static property.
+ * This function helps distinguish between Angular modules and bootstrap functions.
+ *
+ * @param value - The value to be checked.
+ * @returns True if the value is an Angular module (i.e., it has the `ɵmod` property), false otherwise.
+ */
+export function isNgModule(value) {
+    return 'ɵmod' in value;
+}

package/esm2022/src/utils/url.mjs

@@ -0,0 +1,85 @@
+/**
+ * @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
+ */
+/**
+ * Removes the trailing slash from a URL if it exists.
+ *
+ * @param url - The URL string from which to remove the trailing slash.
+ * @returns The URL string without a trailing slash.
+ *
+ * @example
+ * ```js
+ * stripTrailingSlash('path/'); // 'path'
+ * stripTrailingSlash('/path');  // '/path'
+ * ```
+ */
+export function stripTrailingSlash(url) {
+    // Check if the last character of the URL is a slash
+    return url[url.length - 1] === '/' ? url.slice(0, -1) : url;
+}
+/**
+ * Joins URL parts into a single URL string.
+ *
+ * This function takes multiple URL segments, normalizes them by removing leading
+ * and trailing slashes where appropriate, and then joins them into a single URL.
+ *
+ * @param parts - The parts of the URL to join. Each part can be a string with or without slashes.
+ * @returns The joined URL string, with normalized slashes.
+ *
+ * @example
+ * ```js
+ * joinUrlParts('path/', '/to/resource'); // '/path/to/resource'
+ * joinUrlParts('/path/', 'to/resource'); // '/path/to/resource'
+ * ```
+ */
+export function joinUrlParts(...parts) {
+    // Initialize an array with an empty string to always add a leading slash
+    const normalizeParts = [''];
+    for (const part of parts) {
+        if (part === '') {
+            // Skip any empty parts
+            continue;
+        }
+        let normalizedPart = part;
+        if (part[0] === '/') {
+            normalizedPart = normalizedPart.slice(1);
+        }
+        if (part[part.length - 1] === '/') {
+            normalizedPart = normalizedPart.slice(0, -1);
+        }
+        if (normalizedPart !== '') {
+            normalizeParts.push(normalizedPart);
+        }
+    }
+    return normalizeParts.join('/');
+}
+/**
+ * Strips `/index.html` from the end of a URL's path, if present.
+ *
+ * This function is used to convert URLs pointing to an `index.html` file into their directory
+ * equivalents. For example, it transforms a URL like `http://www.example.com/page/index.html`
+ * into `http://www.example.com/page`.
+ *
+ * @param url - The URL object to process.
+ * @returns A new URL object with `/index.html` removed from the path, if it was present.
+ *
+ * @example
+ * ```typescript
+ * const originalUrl = new URL('http://www.example.com/page/index.html');
+ * const cleanedUrl = stripIndexHtmlFromURL(originalUrl);
+ * console.log(cleanedUrl.href); // Output: 'http://www.example.com/page'
+ * ```
+ */
+export function stripIndexHtmlFromURL(url) {
+    if (url.pathname.endsWith('/index.html')) {
+        const modifiedURL = new URL(url);
+        // Remove '/index.html' from the pathname
+        modifiedURL.pathname = modifiedURL.pathname.slice(0, /** '/index.html'.length */ -11);
+        return modifiedURL;
+    }
+    return url;
+}