@ng-doc/builder 22.0.0-beta.2 → 22.1.0

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

@@ -0,0 +1,212 @@
+import type { BuildResult, FileChange, OutputManifest } from '../contracts.js';
+type EventType = 'create' | 'update' | 'delete';
+export interface PhysicalState {
+    digest?: string;
+    version: string;
+}
+export interface HostUpdateTicket {
+    readonly ready: Promise<void>;
+    readonly token: object;
+}
+export interface InitialCompilationInventory {
+    readonly files: ReadonlyArray<{
+        path: string;
+        digest: string;
+    }>;
+    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.
+ *
+ * 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.
+ */
+export declare class HostUpdateCoordinator {
+    private readonly notify;
+    private readonly fail;
+    private readonly recovery?;
+    private outputRoot?;
+    private manifest?;
+    private announcedManifest?;
+    private pendingManifest?;
+    private publishedGeneration?;
+    private latestAttempt?;
+    private readonly attempts;
+    private readonly pendingSources;
+    private readonly claimedSources;
+    private readonly blockers;
+    private readonly diagnosticFailures;
+    /** How many compiler diagnostics were ever recorded: the mark a pass takes when it starts. */
+    private diagnosticRecords;
+    /** Each Vite hot update's token, by that event's `read` function (shared by all its hooks). */
+    private readonly tokensByEvent;
+    private diagnosticChanged;
+    private outputDrain;
+    private hostDrain;
+    private pendingGeneration?;
+    private sequence;
+    private disposed;
+    private burst?;
+    /** The start and the hot updates of the current burst-detection window. */
+    private window;
+    constructor(notify: () => void, fail: (error: Error) => void, recovery?: HostUpdateRecovery | undefined);
+    seed(outputRoot: string, manifest: OutputManifest): void;
+    initialCompilationInventory(): InitialCompilationInventory;
+    started(generation: number, changes: FileChange[]): void;
+    /**
+     * The session discarded these source changes as unchanged saves, so no generation will claim
+     * their pending hot updates. They are released unclaimed, as for a file outside the generator's
+     * inputs: a plain source completes at once, and a compiler source requests the current reload
+     * after its own Angular acknowledgment. A later generation that lists the path claims only
+     * hot updates begun after this call.
+     */
+    unchanged(changes: FileChange[]): void;
+    result(result: BuildResult): void;
+    publication(generation: number, status: 'success' | 'failure' | 'skipped' | 'cancelled', error?: Error): void;
+    begin(file: string, type: EventType, read: () => string | Promise<string>, relevantSource: boolean): HostUpdateTicket;
+    /**
+     * Records this exact host hook's compiler acknowledgment without waiting on peer hooks.
+     *
+     * @param recoverBefore A {@link diagnosticMark} taken when a successful whole-program pass
+     *   started: every diagnostic recorded before it is repaired too, whatever its hook's order.
+     */
+    acknowledge(ticket: HostUpdateTicket, resourceWitness?: boolean, compilerPass?: boolean, recoverBefore?: number): Promise<void>;
+    /**
+     * Whether this coordinator announces the hot update identified by `read` itself: a committed
+     * 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.
+     */
+    announces(read: object): boolean;
+    /**
+     * The other TypeScript outputs that the generation of this generated TypeScript update created
+     * or changed in place and whose own hot updates have not completed yet. The Angular composition
+     * compiles them in this update's pass, so a later report of any of them with the same bytes (a
+     * created output reported as changed, a repeated change) takes no pass of its own. Call it after
+     * `ticket.ready`, which binds the generation.
+     */
+    compilerCompanions(ticket: HostUpdateTicket): string[];
+    /**
+     * 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.
+     * @param file An absolute path.
+     */
+    generated(file: string): boolean;
+    /** A failed compiler candidate is observed, but never acknowledged as successful. */
+    diagnostic(ticket: HostUpdateTicket, error: Error): void;
+    diagnosticError(): Error | undefined;
+    /** 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 candidate's atomic commit boundary, including a failure that kept last-good. */
+    committed(ticket: HostUpdateTicket): Promise<void>;
+    complete(ticket: HostUpdateTicket): Promise<void>;
+    published(result: Extract<BuildResult, {
+        status: 'success';
+    }>, recovered: boolean): void;
+    dispose(): void;
+    blockerCount(): number;
+    private defineExpected;
+    private prepareGenerated;
+    private findMatchingAttempt;
+    /**
+     * Binds a report of an output whose expectation its generation already completed, while the
+     * file is still the one that generation wrote. Vite's own reload for it would be a second one
+     * (the adapter reloaded for that generation), and it obliges no further compiler pass.
+     * @param token A generated output's report that matched no open expectation.
+     */
+    private bindRepeat;
+    private prepareSource;
+    private attachExpected;
+    private matches;
+    private resolveShapes;
+    private claimSource;
+    /**
+     * A claimed source that only a compiler pass can witness (a created or deleted TypeScript
+     * source, a resource without its own witness) waits for its generation's compiled update of a
+     * generated TypeScript output: that pass reads the program with the source in it. A generation
+     * that rewrites no such output (a category without pages, a new component file no page imports
+     * yet, an edit whose outputs are data modules only) never takes that pass, so once its result is
+     * known and every such update of it has completed, its sources are released; otherwise the edit
+     * never settled (`NGDOC_VITE_HOST_TIMEOUT`).
+     */
+    private releaseUnwitnessedSources;
+    private supersedeOlderPath;
+    private supersedeOlderSource;
+    private sourceBlocker;
+    private addBlocker;
+    private clearBlocker;
+    private hasOutputBlockers;
+    private flush;
+    private queueCurrentReload;
+    private awaitCurrentPublication;
+    private awaitWithoutDiagnostic;
+    private delta;
+    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 {};

package/generator/vite/index.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from 'vite';
+import type { NgDocVitePluginOptions } from './options.js';
+export type { NgDocVitePluginOptions } from './options.js';
+/** Physical-output Vite integration which owns the supplied complete Analog Angular plugin array. */
+export declare function createNgDocVitePlugin(options: NgDocVitePluginOptions): Plugin[];
+export type { NgDocViteApplicationOptions, NgDocViteAssetPattern } from './application.js';
+export { createNgDocApplicationPlugin, NG_DOC_BROWSER_ENTRY, NG_DOC_SERVER_ENTRY, } from './application.js';
+export type { NgDocExcludedRoute, NgDocPrerenderOptions, NgDocPrerenderReport, NgDocPrerenderRoute, } from './prerender.js';
+export { prerenderNgDoc } from './prerender.js';
+export type { NgDocViteBuildOptions, NgDocViteBuildResult } from './production.js';
+export { buildNgDocViteApplication } from './production.js';
+export type { NgDocSsrJsonValue, NgDocSsrRequest, NgDocViteSsrRenderer } from './ssr-renderer.js';
+export { getNgDocViteSsrRenderer } from './ssr-renderer.js';