@ng-doc/builder 22.0.0-beta.1 → 22.0.0

package/generator/worker/index.d.ts

@@ -0,0 +1,156 @@
+import type { CompilationAcknowledgement, CompilationRequest, CompilationResult, CompilationService, JsonValue } from '../contracts.js';
+/** Long-lived development runtime limits (see `createWorkerCompilationService`). */
+export interface PersistentWorkerOptions {
+    /** Cooperative abort grace before the runtime is SIGKILLed. Defaults to 1500 ms. */
+    abortGraceMs?: number;
+    /** An idle runtime that served this many generations is replaced. Defaults to 50. */
+    maxGenerations?: number;
+    /** An idle runtime whose resident set exceeds this many bytes is replaced. Defaults to 3 GiB. */
+    maxRssBytes?: number;
+    /**
+     * Allow `prime`: a warm-up of the long-lived runtime at idle, so that its compiler already
+     * retains a program when the first edit arrives. With it, a development generation before the
+     * first watch (the startup buildOnce) also runs in that runtime, so the warm-up usually finds the
+     * program there and compiles nothing. Defaults to true.
+     */
+    prime?: boolean;
+    /**
+     * Delta transport between the session and this runtime. Defaults to true. The runtime keeps the
+     * committed snapshot of its base, so a request carries only its changes and base revision, and a
+     * result returns only the changed artifacts (`SnapshotDelta`); the host rebuilds the complete
+     * candidate against the caller's snapshot. The full snapshot crosses only on a resync (a fresh or
+     * recycled runtime, or a base the runtime does not retain). A working candidate becomes the
+     * runtime's base only after `acknowledge` reports its commit. `false` keeps the full transport.
+     * `'verify'` also sends the full candidate and checks the rebuilt one against it (falling back to
+     * it on any difference), and freezes retained snapshots so that an in-place mutation throws: for
+     * tests and diagnosis only, it costs more than the full transport.
+     */
+    delta?: boolean | 'verify';
+}
+/** Counters of the delta transport (instrumentation and tests). */
+export interface DeltaTransportStatistics {
+    /** Results whose candidate was rebuilt from a delta. */
+    deltas: number;
+    /** Resyncs that sent the caller's full previous snapshot. */
+    snapshotResyncs: number;
+    /** Compiles that promoted the runtime's working snapshot (acknowledged commits). */
+    promotions: number;
+    /** Delta compiles retried with a resync (and, after an unusable delta, a full candidate). */
+    fallbacks: number;
+    /** `verify` mode: rebuilt candidates that differed from the full one. */
+    mismatches: number;
+    /** Characters of delta-mode messages sent (compile and resync) and of replies received. */
+    sentCharacters: number;
+    receivedCharacters: number;
+    /** The last reply-time and idle (after the runtime's collection) resident set sizes, in bytes. */
+    replyRss?: number;
+    idleRss?: number;
+}
+/**
+ * The targeted rebuild's report as the long-lived runtime returned it (see compiler/dry-run.ts):
+ * the runtime's own output is not forwarded, so each compile returns its record with the reply. A
+ * record with misses or a mismatch (`NGDOC_TARGETED_REBUILD=verify`) is reported as a
+ * `COMPILATION_TARGETED_MISMATCH` process warning here.
+ */
+export interface TargetedDryRunStatistics {
+    /** Compiles that returned a record / records with misses or a targeted-versus-full mismatch. */
+    records: number;
+    misses: number;
+    /** The last record, as the compiler wrote it (JSON). */
+    last?: unknown;
+}
+/** What a `prime` call did. It never carries a candidate. */
+export type PrimeOutcome = 
+/** The runtime compiled the request; `revision` is the candidate its compiler retained for. */
+{
+    status: 'primed';
+    revision: string;
+} | {
+    status: 'skipped';
+    reason: string;
+}
+/** Superseded by a compile, the watch stopping, the caller's signal, or dispose. */
+ | {
+    status: 'aborted';
+} | {
+    status: 'failed';
+    code: string;
+    message: string;
+};
+/** A worker compiler with the optional warm-up hook the build session looks for. */
+export interface WorkerCompilationService extends CompilationService {
+    /**
+     * Present only with the persistent runtime and priming enabled (`persistent.prime`).
+     *
+     * Compiles `request` (a development request whose `previous` is the committed snapshot) in the
+     * long-lived development runtime only to warm it: the compiler retains that generation's
+     * program for the candidate revision, and the candidate itself never leaves the runtime. A
+     * runtime that already retains a program for that revision (it compiled the startup
+     * generation) returns at once. It runs only while idle and watching (otherwise it is
+     * `skipped`), and every later `compile` (or the watch stopping) supersedes it through the
+     * ordinary abort path.
+     */
+    prime?(request: CompilationRequest, signal: AbortSignal): Promise<PrimeOutcome>;
+    /** Present only with the persistent runtime and the delta transport (`persistent.delta`). */
+    acknowledge?(acknowledgement: CompilationAcknowledgement): void;
+    /** Counters of the delta transport since the service was created. */
+    transport(): DeltaTransportStatistics;
+    /** The targeted rebuild's records the long-lived runtime returned. */
+    targetedDryRun(): TargetedDryRunStatistics;
+    /**
+     * Whether `result` (as this service returned it) came from a targeted generation, whose
+     * commit may be a delta against the committed snapshot. A full generation's commit must be the
+     * full commit, which re-verifies every output.
+     */
+    targetedResult(result: CompilationResult): boolean;
+}
+export interface WorkerCompilationOptions {
+    /** Absolute ESM URL exporting createCompilationService(options). */
+    moduleUrl: string | URL;
+    factoryOptions?: JsonValue;
+    startupTimeoutMs?: number;
+    compileTimeoutMs?: number;
+    /** Active plus queued requests. Defaults to 8. */
+    maxPendingRequests?: number;
+    /** Default resolves beside this published ESM module. Also supports bundled test runtimes. */
+    workerEntryUrl?: URL;
+    /**
+     * The long-lived runtime used for development watch generations (`context.lifetime` `watch`).
+     * `false` runs every generation in its own disposable runtime. Defaults to enabled.
+     */
+    persistent?: boolean | PersistentWorkerOptions;
+}
+/**
+ * One disposable runtime per generation bounds executable module lifetime. No output writes occur
+ * here.
+ *
+ * Exception, development watch generations only (`context.lifetime === 'watch'`): they share one
+ * long-lived runtime per watch session, which removes the per-generation fork, compiler-bundle
+ * import and warm-up. User modules keep their per-generation lifetime there too: the runtime
+ * creates a fresh compilation service for every generation and disposes it (its discovery and
+ * template evaluation scopes, timers and network) before replying. Host-realm state is made
+ * per-generation too (entry.ts `isolate`): the host's current env and cwd are sent with every
+ * compile, and afterwards env, cwd, umask and `exitCode` are restored, process listeners added by
+ * the generation are removed, and user (non-`node_modules`) CommonJS modules it loaded are evicted
+ * from the require cache; a user ES module loaded through `require` cannot be evicted, so its
+ * runtime is replaced before the next generation. Mutations of shared builtin modules cannot be
+ * undone; the recycle bound is their backstop. The runtime exits when the host disconnects. It is
+ * replaced when it crashes, exceeds a deadline, ignores a cooperative abort for `abortGraceMs`
+ * (SIGKILL), or, while idle, after `maxGenerations` generations or above `maxRssBytes`; the next
+ * generation then runs in a new, cold runtime. It ends when the watch stops and no watch
+ * generation is running or queued. buildOnce, production and callers without a context use a
+ * fresh one-shot runtime, except a development generation before the first watch while warm-ups
+ * are allowed (`servesStartup`).
+ *
+ * Every runtime tells its compiler how long it lives (`context.lifetime`: `watch` in the
+ * long-lived runtime, `generation` in a one-shot one), so only the long-lived runtime retains a
+ * program. `prime` warms that runtime while idle (see `WorkerCompilationService.prime`).
+ *
+ * Delta transport (`PersistentWorkerOptions.delta`), for callers that pass `context.delta` (the
+ * build session's watch generations): the request crosses without its previous snapshot whenever
+ * the runtime retains that snapshot, the result crosses as a `SnapshotDelta` that is applied here
+ * to the caller's own snapshot, and the runtime promotes a candidate to its base only after
+ * `acknowledge` reports its commit. A fresh or recycled runtime, a base the runtime does not hold,
+ * or any disagreement costs one resync with the full snapshot.
+ */
+export declare function createWorkerCompilationService(options: WorkerCompilationOptions): WorkerCompilationService;