@ng-doc/builder 22.0.0 → 22.2.0

package/generator/vite/demo-application.d.ts

@@ -0,0 +1,34 @@
+/** The generated module of the demo application, in the output root (`demo-app.ts.nunj`). */
+export declare const DEMO_APPLICATION_MODULE = "demo-app.ts";
+/**
+ * The demo application of a generation: its generated module and the URL path of its pages.
+ * The NgDoc plugin publishes it to the application plugin (`NgDocDemoApplicationApi`).
+ */
+export interface NgDocDemoApplication {
+    /** The generated module (absolute), which exports the routes and the providers import. */
+    readonly module: string;
+    /** The URL path of the demo pages, relative to the base href, without slashes around it. */
+    readonly path: string;
+    /** Every demo page, relative to the base href (`<path>/<page route>/<demo name>`). */
+    readonly pages: readonly string[];
+}
+/**
+ * What the NgDoc plugin offers the application plugin through `api.ngDocDemoApplication`.
+ * @internal
+ */
+export interface NgDocDemoApplicationApi {
+    readonly schemaVersion: 1;
+    /**
+     * The demo application of the build's generation, generating first if the build has not yet: a
+     * build adds the demo page's input before it starts, when there is one.
+     */
+    resolve(): Promise<NgDocDemoApplication | undefined>;
+    /** The demo application of the current generation of the development server, if any. */
+    current(): Promise<NgDocDemoApplication | undefined>;
+}
+/**
+ * Reads the demo application from a committed output root: a generation writes `demo-app.ts`
+ * only when a guide has demo pages, and that module names the URL path of the pages.
+ * @param outputRoot - The output root of the published generation.
+ */
+export declare function readDemoApplication(outputRoot: string): Promise<NgDocDemoApplication | undefined>;

package/generator/vite/dev-server-builder.js

@@ -7,6 +7,7 @@ import { Observable } from "rxjs";
 import { createServer as viteCreateServer } from "vite";
 
 // libs/builder/generator/vite/production.ts
+import { existsSync } from "node:fs";
 import { rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build as viteBuild } from "vite";
@@ -75,7 +76,8 @@ function prerenderNgDoc(options) {
     serverEntry: options.serverEntry,
     routes: [...options.routes ?? []],
     discoverRoutes: options.discoverRoutes ?? true,
-    ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs }
+    ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
+    ...options.demoServerEntry ? { demoServerEntry: options.demoServerEntry } : {}
   };
   if (request.routeTimeoutMs !== void 0 && (!Number.isSafeInteger(request.routeTimeoutMs) || request.routeTimeoutMs < 1)) {
     return Promise.reject(
@@ -256,11 +258,13 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
   }
   const prerender = options.prerender ?? (options.skipBuild ? true : ssr === true);
   if (!prerender) return { browser, ...ssr ? { server: serverEntry } : {} };
+  const demoServerEntry = path.join(serverDirectory, "demo-server.mjs");
   const report = await timed(
     "Prerendered the routes",
     () => dependencies.prerender({
       browserDir: browser,
       serverEntry,
+      ...existsSync(demoServerEntry) && existsSync(path.join(browser, "ng-doc-demo.html")) ? { demoServerEntry } : {},
       routes: options.routes ?? [],
       discoverRoutes: options.discoverRoutes ?? true,
       ...options.routeTimeoutMs === void 0 ? {} : { routeTimeoutMs: options.routeTimeoutMs },
@@ -273,6 +277,7 @@ async function buildNgDocViteApplication(options, dependencies = defaultDependen
 `
   );
   log(`Prerendered ${report.routes.length} route(s) into ${browser}`);
+  for (const { route, message: message2 } of report.warnings ?? []) log(`Warning: ${route}: ${message2}`);
   if (report.errors.length) {
     log(`The application logged ${report.errors.length} error(s) while prerendering:`);
     for (const { route, message: message2 } of report.errors.slice(0, 10)) log(`  ${route}: ${message2}`);

package/generator/vite/host-updates.d.ts

@@ -4,6 +4,24 @@ export interface PhysicalState {
     digest?: string;
     version: string;
 }
+export interface ManifestFile {
+    digest: string;
+    role: OutputManifest['files'][number]['role'];
+}
+/**
+ * One generated file whose bytes or role differ between the outputs the browser was last told
+ * about and the outputs a reload announces now.
+ */
+export interface AnnouncedChange {
+    /** Relative to the output root, with forward slashes, as the manifest lists it. */
+    readonly path: string;
+    /** The absolute path. */
+    readonly file: string;
+    /** Absent for a created file. */
+    readonly before?: Readonly<ManifestFile>;
+    /** Absent for a deleted file. */
+    readonly after?: Readonly<ManifestFile>;
+}
 export interface HostUpdateTicket {
     readonly ready: Promise<void>;
     readonly token: object;
@@ -15,13 +33,60 @@ export interface InitialCompilationInventory {
     }>;
     isCurrent(): boolean;
 }
+/**
+ * What the host does for the coordinator when a burst ends (see {@link HostUpdateCoordinator}).
+ */
+export interface HostUpdateRecovery {
+    /** Logs a warning: the summary of the host update timeouts a burst held back. */
+    warn(message: string): void;
+    /**
+     * Reports `file` again as its watcher would have: a generated output whose report never
+     * completed its generation's expectation (lost, or its hook timed out and threw).
+     */
+    replay(file: string, type: 'create' | 'update' | 'delete'): void;
+    /** Re-observes every recorded input before the next generation (`BuildSession.rescan`). */
+    rescan(): void;
+}
+/** How long a host update waits for the publication's host obligations to drain. */
+export declare const HOST_COMPLETION_TIMEOUT_MS = 30000;
+/** Hot updates within {@link HOST_BURST_WINDOW_MS} that open a burst of file events. */
+export declare const HOST_BURST_EVENTS = 1000;
+/** The window in which {@link HOST_BURST_EVENTS} hot updates open a burst. */
+export declare const HOST_BURST_WINDOW_MS = 1000;
+/** A burst ends after this long without a hot update or a host update timeout. */
+export declare const HOST_BURST_QUIET_MS = 2000;
 export declare function observePhysicalState(file: string, read?: () => string | Promise<string>): Promise<PhysicalState>;
 /** A synchronous metadata-only stamp preserves the event-time identity without starting I/O queues. */
 export declare function observePhysicalVersion(file: string): string | undefined;
-/** Coordinates committed generator versions with Vite's client hot-update pipeline. */
+/**
+ * Coordinates committed generator versions with Vite's client hot-update pipeline.
+ *
+ * Bursts: thousands of file events at once (a script or a checkout writing many files) flood
+ * Vite's hot-update pipeline and the watcher. Host updates then wait longer than
+ * {@link HOST_COMPLETION_TIMEOUT_MS}, a hook that timed out leaves its generation's obligation
+ * open (nothing reports that output again, so no reload is ever sent), and chokidar may lose
+ * events without any signal. So a burst is tracked: it opens with {@link HOST_BURST_EVENTS} hot
+ * updates of files outside the output root (once the first generation is published) within
+ * {@link HOST_BURST_WINDOW_MS}, or with a host update timeout, and ends after
+ * {@link HOST_BURST_QUIET_MS} without either. Only its first timeout is reported as it happens;
+ * the others are summed up in one warning when it ends. Then it takes one more pass: every
+ * generated output whose report never completed its expectation, and whose file is still what
+ * its generation wrote, is reported again (`HostUpdateRecovery.replay`), and every recorded
+ * input is re-observed (`HostUpdateRecovery.rescan`), so the newest edit is published even if
+ * its event was lost or its generation failed under the load. A replayed report is matched like
+ * any other: one that arrives twice is a repeat, so an edit still reloads once.
+ *
+ * Churn: under a sustained stream of edits a new generation starts before the previous one is
+ * published, again and again. A host update that waits for the current publication follows each
+ * newer generation, so it settles only once the stream stops. That is required of one whose hook
+ * hands Vite modules: Vite updates them when the hook returns, which must not happen before the
+ * newest publication. A module-less one hands Vite nothing, so it settles once it is acknowledged
+ * (see {@link settle}; `NGDOC_VITE_MODULELESS_SETTLE=0` makes it wait as well).
+ */
 export declare class HostUpdateCoordinator {
     private readonly notify;
     private readonly fail;
+    private readonly recovery?;
     private outputRoot?;
     private manifest?;
     private announcedManifest?;
@@ -43,7 +108,24 @@ export declare class HostUpdateCoordinator {
     private pendingGeneration?;
     private sequence;
     private disposed;
-    constructor(notify: () => void, fail: (error: Error) => void);
+    private burst?;
+    /** The start and the hot updates of the current burst-detection window. */
+    private window;
+    /** Whether a module-less host update settles without waiting for the current publication. */
+    private readonly modulelessSettle;
+    /**
+     * Whether the pending reload must reload the page whatever its outputs: an Angular source was
+     * compiled for it, or it repairs an earlier failure (the browser shows the error overlay).
+     */
+    private pendingFull;
+    /**
+     * @param notify Announces the newest settled publication to the browser. `changes` lists the
+     *   generated files that differ from the last announcement, when nothing else asks for a full
+     *   reload; without it, or when the host cannot apply the changes in place, the page reloads.
+     * @param fail Reports a host error.
+     * @param recovery What the host does after a burst.
+     */
+    constructor(notify: (changes?: readonly AnnouncedChange[]) => void, fail: (error: Error) => void, recovery?: HostUpdateRecovery | undefined);
     seed(outputRoot: string, manifest: OutputManifest): void;
     initialCompilationInventory(): InitialCompilationInventory;
     started(generation: number, changes: FileChange[]): void;
@@ -70,7 +152,8 @@ export declare class HostUpdateCoordinator {
      * generated output that a generation claimed. Its host hooks settle only once the newest
      * generation is published and every host obligation is drained, and by then `flush()` has sent
      * that generation's reload (or its outputs equal the last announced ones). A native reload for
-     * the same output would be a second one.
+     * the same output would be a second one. A module-less one settles earlier (see
+     * {@link settle}), but Vite has nothing of it to reload either way.
      */
     announces(read: object): boolean;
     /**
@@ -81,6 +164,16 @@ export declare class HostUpdateCoordinator {
      * `ticket.ready`, which binds the generation.
      */
     compilerCompanions(ticket: HostUpdateTicket): string[];
+    /**
+     * Whether the generation that claimed this TypeScript source update committed and still has a
+     * generated TypeScript module update whose Angular pass has not completed: that pass is still to
+     * come, and the source can join it (`ngDocCompanionFiles`) instead of taking a pass of its own.
+     * False for anything else: a generated output, a source no generation claimed, a generation
+     * that failed, was cancelled or rewrote no TypeScript module, or whose passes all completed.
+     * Call it after `committed(ticket)`, which waits for the generation's result.
+     * @param ticket The source's hot update ticket.
+     */
+    generationPass(ticket: HostUpdateTicket): boolean;
     /**
      * Whether `file` is a generated output: a path below the output root of the published
      * generation. Nothing is generated before the first publication or after disposal.
@@ -93,11 +186,30 @@ export declare class HostUpdateCoordinator {
     /** The diagnostics recorded so far; a pass that starts now can repair exactly these. */
     diagnosticMark(): number;
     private recoverDiagnostics;
-    /** Waits for the current accepted publication and all peer host acknowledgments. */
-    settle(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * Waits for the current accepted publication and all peer host acknowledgments.
+     *
+     * A module-less hot update does not wait: once its hooks return, Vite has no module to update
+     * and sends nothing, and its acknowledgment has already settled what it obliged (the reload,
+     * sent by `flush()` once every obligation is settled, is this coordinator's own). Waiting made
+     * it follow every generation that started meanwhile, so under sustained churn it settled only
+     * when the churn stopped, and each wait for the host obligations to drain could time out
+     * (`NGDOC_VITE_HOST_TIMEOUT`) while every single obligation was completed in time. Nothing
+     * else changes: obligations, the reload and what is published are the same, so the switch off
+     * (`NGDOC_VITE_MODULELESS_SETTLE=0`) only makes it wait as before.
+     * @param ticket The hot update's ticket, after its acknowledgment.
+     * @param modules Whether its hooks hand Vite any module to update (or a page reload Vite sends
+     *   itself, for an HTML file without modules). Only the caller, which sees Vite's context, knows.
+     */
+    settle(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     /** Waits for the candidate's atomic commit boundary, including a failure that kept last-good. */
     committed(ticket: HostUpdateTicket): Promise<void>;
-    complete(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * Acknowledges a hot update that takes no compiler pass, then settles it.
+     * @param ticket The hot update's ticket.
+     * @param modules See {@link settle}.
+     */
+    complete(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     published(result: Extract<BuildResult, {
         status: 'success';
     }>, recovered: boolean): void;
@@ -136,10 +248,45 @@ export declare class HostUpdateCoordinator {
     private hasOutputBlockers;
     private flush;
     private queueCurrentReload;
+    /**
+     * Settles a module-less hot update without waiting (see {@link settle}).
+     * @param token The acknowledged hot update.
+     */
+    private settleModuleless;
     private awaitCurrentPublication;
     private awaitWithoutDiagnostic;
     private delta;
+    /**
+     * The generated files that differ between two manifests, in path order.
+     * @param previousManifest The outputs the browser was last told about.
+     * @param nextManifest The outputs announced now.
+     */
+    private changes;
     private prune;
     private withTimeout;
+    /** Counts a hot update towards a burst of file events (see the class description). */
+    private hotUpdate;
+    /**
+     * A host update did not settle in time. The first of a burst is reported as it happens (as
+     * every timeout was before); the others only count towards the burst's summary, so a flood of
+     * file events logs two lines instead of one per event.
+     * @param failure The timeout, thrown to its waiter as well.
+     */
+    private timedOut;
+    private openBurst;
+    /**
+     * One timer per burst, re-armed for the rest of the quiet period when activity moved `last`.
+     * @param burst The open burst.
+     * @param delay When to check it next.
+     */
+    private armBurst;
+    /**
+     * The pass after a burst: the summary of its held-back timeouts, then every open output
+     * obligation whose file is still what its generation wrote is reported again, in path order,
+     * and every recorded input is re-observed once no generation is in flight. An output a newer generation rewrote since is left
+     * to that generation's own report, which supersedes the older expectation.
+     * @param burst The burst that ended.
+     */
+    private recover;
 }
 export {};