diff --git a/goldens/public-api/angular/ssr/index.api.md b/goldens/public-api/angular/ssr/index.api.md index 23d13774aba3..6d89972bde20 100644 --- a/goldens/public-api/angular/ssr/index.api.md +++ b/goldens/public-api/angular/ssr/index.api.md @@ -4,6 +4,17 @@ ```ts +// @public +export interface AngularServerAppManager { + render(request: Request, requestContext?: unknown): Promise; +} + +// @public +export function destroyAngularAppEngine(): void; + +// @public +export function getOrCreateAngularAppEngine(): AngularServerAppManager; + // (No @packageDocumentation comment for this package) ``` diff --git a/packages/angular/ssr/private_export.ts b/packages/angular/ssr/private_export.ts index 9772d2252afc..9c5573471467 100644 --- a/packages/angular/ssr/private_export.ts +++ b/packages/angular/ssr/private_export.ts @@ -17,4 +17,6 @@ export { setAngularAppEngineManifest as ɵsetAngularAppEngineManifest, } from './src/manifest'; +export { AngularAppEngine as ɵAngularAppEngine } from './src/app-engine'; + export { InlineCriticalCssProcessor as ɵInlineCriticalCssProcessor } from './src/utils/inline-critical-css'; diff --git a/packages/angular/ssr/public_api.ts b/packages/angular/ssr/public_api.ts index e714ba0d0e44..71647188bc13 100644 --- a/packages/angular/ssr/public_api.ts +++ b/packages/angular/ssr/public_api.ts @@ -7,3 +7,9 @@ */ export * from './private_export'; + +export { + type AngularServerAppManager, + getOrCreateAngularAppEngine, + destroyAngularAppEngine, +} from './src/app-engine'; diff --git a/packages/angular/ssr/src/app-engine.ts b/packages/angular/ssr/src/app-engine.ts index fa501c33510c..c76be807c223 100644 --- a/packages/angular/ssr/src/app-engine.ts +++ b/packages/angular/ssr/src/app-engine.ts @@ -10,20 +10,45 @@ import { Hooks } from './hooks'; import { getPotentialLocaleIdFromUrl } from './i18n'; import { EntryPointExports, getAngularAppEngineManifest } from './manifest'; +/** + * Angular server application engine. + * Manages Angular server applications (including localized ones) and handles rendering requests. + + * @developerPreview + */ +export interface AngularServerAppManager { + /** + * 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. + */ + render(request: Request, requestContext?: unknown): Promise; +} + /** * Angular server application engine. * Manages Angular server applications (including localized ones), handles rendering requests, * and optionally transforms index HTML before rendering. */ -export class AngularAppEngine { +export class AngularAppEngine implements AngularServerAppManager { /** * 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 + * @private */ - static hooks = new Hooks(); + static ɵhooks = new Hooks(); /** * Provides access to the hooks for extending or modifying the server application's behavior. @@ -32,7 +57,7 @@ export class AngularAppEngine { * @internal */ get hooks(): Hooks { - return AngularAppEngine.hooks; + return AngularAppEngine.ɵhooks; } /** @@ -92,3 +117,32 @@ export class AngularAppEngine { return entryPoints.get(potentialLocale); } } + +let angularAppEngine: AngularAppEngine | undefined; + +/** + * Retrieves an existing `AngularAppEngine` instance or creates a new one if none exists. + * + * This method ensures that only a single instance of `AngularAppEngine` is created and reused across + * the application lifecycle, providing efficient resource management. If the instance does not exist, + * it will be instantiated upon the first call. + * + * @developerPreview + * @returns The existing or newly created instance of `AngularAppEngine`. + */ +export function getOrCreateAngularAppEngine(): AngularServerAppManager { + return (angularAppEngine ??= new AngularAppEngine()); +} + +/** + * Destroys the current `AngularAppEngine` instance, releasing any associated resources. + * + * This method resets the reference to the `AngularAppEngine` instance to `undefined`, allowing + * a new instance to be created on the next call to `getOrCreateAngularAppEngine()`. It is typically + * used when reinitializing the server environment or refreshing the application state is necessary. + * + * @developerPreview + */ +export function destroyAngularAppEngine(): void { + angularAppEngine = undefined; +}