@dudousxd/nestjs-codegen 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -45,6 +45,18 @@ declare function generate(config: ResolvedConfig, inputRoutes?: RouteDescriptor[
 interface Watcher {
     close(): Promise<void>;
 }
+interface WatchOptions {
+    /**
+     * Run the initial discover + generate as fire-and-forget instead of awaiting it
+     * before returning. The lock is still acquired and the chokidar watchers are
+     * still set up synchronously; only the initial generate is backgrounded. Used by
+     * the Nest `onApplicationBootstrap` hook so codegen never blocks time-to-ready.
+     * The one-shot CLI leaves this `false` so the build step stays synchronous.
+     *
+     * @default false
+     */
+    deferInitialGenerate?: boolean;
+}
 /**
  * Start two chokidar watchers:
  *
@@ -58,7 +70,7 @@ interface Watcher {
  * Both watchers share a single lock file in `config.codegen.outDir`. If another live process
  * already holds the lock, logs a warning and returns a no-op watcher.
  */
-declare function watch(config: ResolvedConfig, onChange?: () => void): Promise<Watcher>;
+declare function watch(config: ResolvedConfig, onChange?: () => void, options?: WatchOptions): Promise<Watcher>;
 
 /**
  * Try to acquire an exclusive lock for a watcher in `outDir`.
@@ -73,6 +85,20 @@ declare function acquireLock(outDir: string): Promise<{
     release: () => Promise<void>;
 } | null>;
 
+/**
+ * Persisted record of the last successful generate, written to
+ * `<outDir>/.codegen-manifest.json`. Used to skip regeneration when nothing
+ * relevant changed (see {@link isManifestFresh}).
+ */
+interface CodegenManifest {
+    /** Lib version that produced the output. A lib upgrade invalidates the manifest. */
+    version: string;
+    /** Content hash over all generate inputs (source files + resolved config + version). */
+    hash: string;
+    /** Generated output files, relative to `outDir`, recorded after the last run. */
+    files: string[];
+}
+
 /**
  * Renders the neutral {@link SchemaNode} IR to a TypeScript *type* expression
  * (not a validation-lib schema). Used to synthesize the hoisted structural type
@@ -296,6 +322,6 @@ interface FastDiscoveryOptions {
 }
 declare function discoverContractsFast(opts: FastDiscoveryOptions): Promise<RouteDescriptor[]>;
 
-declare const VERSION = "0.11.0";
+declare const VERSION = "0.12.0";
 
-export { type ChainModuleRendererOptions, CodegenError, ConfigError, type FastDiscoveryOptions, type JsonSchema, type MocksEmitOptions, type OpenApiDocument, type OpenApiEmitOptions, type OpenApiInfo, RenderContext, RenderedModule, ResolvedConfig, RouteDescriptor, SchemaModule, SchemaNode, type TsTypeContext, UserConfig, VERSION, ValidationAdapter, type Watcher, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };
+export { type ChainModuleRendererOptions, CodegenError, type CodegenManifest, ConfigError, type FastDiscoveryOptions, type JsonSchema, type MocksEmitOptions, type OpenApiDocument, type OpenApiEmitOptions, type OpenApiInfo, RenderContext, RenderedModule, ResolvedConfig, RouteDescriptor, SchemaModule, SchemaNode, type TsTypeContext, UserConfig, VERSION, ValidationAdapter, type WatchOptions, type Watcher, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };

package/dist/index.d.ts

@@ -45,6 +45,18 @@ declare function generate(config: ResolvedConfig, inputRoutes?: RouteDescriptor[
 interface Watcher {
     close(): Promise<void>;
 }
+interface WatchOptions {
+    /**
+     * Run the initial discover + generate as fire-and-forget instead of awaiting it
+     * before returning. The lock is still acquired and the chokidar watchers are
+     * still set up synchronously; only the initial generate is backgrounded. Used by
+     * the Nest `onApplicationBootstrap` hook so codegen never blocks time-to-ready.
+     * The one-shot CLI leaves this `false` so the build step stays synchronous.
+     *
+     * @default false
+     */
+    deferInitialGenerate?: boolean;
+}
 /**
  * Start two chokidar watchers:
  *
@@ -58,7 +70,7 @@ interface Watcher {
  * Both watchers share a single lock file in `config.codegen.outDir`. If another live process
  * already holds the lock, logs a warning and returns a no-op watcher.
  */
-declare function watch(config: ResolvedConfig, onChange?: () => void): Promise<Watcher>;
+declare function watch(config: ResolvedConfig, onChange?: () => void, options?: WatchOptions): Promise<Watcher>;
 
 /**
  * Try to acquire an exclusive lock for a watcher in `outDir`.
@@ -73,6 +85,20 @@ declare function acquireLock(outDir: string): Promise<{
     release: () => Promise<void>;
 } | null>;
 
+/**
+ * Persisted record of the last successful generate, written to
+ * `<outDir>/.codegen-manifest.json`. Used to skip regeneration when nothing
+ * relevant changed (see {@link isManifestFresh}).
+ */
+interface CodegenManifest {
+    /** Lib version that produced the output. A lib upgrade invalidates the manifest. */
+    version: string;
+    /** Content hash over all generate inputs (source files + resolved config + version). */
+    hash: string;
+    /** Generated output files, relative to `outDir`, recorded after the last run. */
+    files: string[];
+}
+
 /**
  * Renders the neutral {@link SchemaNode} IR to a TypeScript *type* expression
  * (not a validation-lib schema). Used to synthesize the hoisted structural type
@@ -296,6 +322,6 @@ interface FastDiscoveryOptions {
 }
 declare function discoverContractsFast(opts: FastDiscoveryOptions): Promise<RouteDescriptor[]>;
 
-declare const VERSION = "0.11.0";
+declare const VERSION = "0.12.0";
 
-export { type ChainModuleRendererOptions, CodegenError, ConfigError, type FastDiscoveryOptions, type JsonSchema, type MocksEmitOptions, type OpenApiDocument, type OpenApiEmitOptions, type OpenApiInfo, RenderContext, RenderedModule, ResolvedConfig, RouteDescriptor, SchemaModule, SchemaNode, type TsTypeContext, UserConfig, VERSION, ValidationAdapter, type Watcher, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };
+export { type ChainModuleRendererOptions, CodegenError, type CodegenManifest, ConfigError, type FastDiscoveryOptions, type JsonSchema, type MocksEmitOptions, type OpenApiDocument, type OpenApiEmitOptions, type OpenApiInfo, RenderContext, RenderedModule, ResolvedConfig, RouteDescriptor, SchemaModule, SchemaNode, type TsTypeContext, UserConfig, VERSION, ValidationAdapter, type WatchOptions, type Watcher, acquireLock, buildMocksFile, buildOpenApiSpec, createChainModuleRenderer, defineConfig, discoverContractsFast, emitApi, emitForms, emitMocks, emitOpenApi, emitRoutes, extractSchemaFromDto, generate, loadConfig, renderTsType, resolveConfig, schemaModuleToJsonSchema, schemaNodeToJsonSchema, toObjectKey, typeNameFor, watch };

package/dist/index.js

@@ -188,8 +188,8 @@ Run \`nestjs-codegen init\` to create a starter config.`
 }
 
 // src/generate.ts
-import { mkdir as mkdir9, writeFile as writeFile9 } from "fs/promises";
-import { dirname as dirname2, join as join12 } from "path";
+import { mkdir as mkdir9, writeFile as writeFile10 } from "fs/promises";
+import { dirname as dirname2, join as join13 } from "path";
 
 // src/discovery/pages.ts
 import { readFile } from "fs/promises";
@@ -2087,6 +2087,99 @@ function buildEmpty() {
   ].join("\n");
 }
 
+// src/generate-manifest.ts
+import { createHash } from "crypto";
+import { readFile as readFile2, readdir, writeFile as writeFile9 } from "fs/promises";
+import { join as join12, relative as relative6 } from "path";
+import fg2 from "fast-glob";
+var MANIFEST_FILE = ".codegen-manifest.json";
+var LOCK_FILE = ".watcher.lock";
+function isManifestShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (typeof candidate.version !== "string") return false;
+  if (typeof candidate.hash !== "string") return false;
+  if (!Array.isArray(candidate.files)) return false;
+  return candidate.files.every((entry) => typeof entry === "string");
+}
+function serializeConfig(config) {
+  try {
+    return JSON.stringify(config, (_key, value) => {
+      if (typeof value === "function") return `[fn:${value.name}]${value.toString()}`;
+      return value;
+    });
+  } catch {
+    return `unserializable:${config.codegen.outDir}:${config.contracts.glob}`;
+  }
+}
+async function discoverInputFiles(config) {
+  const globs = [config.contracts.glob, config.forms.watch];
+  if (config.pages) globs.push(config.pages.glob);
+  const cwd = config.codegen.cwd;
+  const matched = await fg2(globs, { cwd, absolute: true, onlyFiles: true });
+  return [...new Set(matched)].sort();
+}
+async function computeInputsHash(config) {
+  const hash = createHash("sha256");
+  hash.update(`version:${VERSION}
+`);
+  hash.update(`config:${serializeConfig(config)}
+`);
+  const inputFiles = await discoverInputFiles(config);
+  const cwd = config.codegen.cwd;
+  for (const file of inputFiles) {
+    const contents = await readFile2(file, "utf8");
+    hash.update(`file:${relative6(cwd, file)}
+`);
+    hash.update(contents);
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+async function readManifest(outDir) {
+  try {
+    const raw = await readFile2(join12(outDir, MANIFEST_FILE), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isManifestShape(parsed)) return null;
+    return { version: parsed.version, hash: parsed.hash, files: parsed.files };
+  } catch {
+    return null;
+  }
+}
+async function writeManifest(outDir, manifest) {
+  await writeFile9(join12(outDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+}
+async function listOutputFiles(outDir) {
+  const found = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      const abs = join12(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(abs);
+      } else if (entry.isFile()) {
+        const rel = relative6(outDir, abs);
+        if (rel === MANIFEST_FILE || rel === LOCK_FILE) continue;
+        found.push(rel);
+      }
+    }
+  }
+  await walk(outDir);
+  return found.sort();
+}
+async function allOutputsExist(outDir, files) {
+  const present = new Set(await listOutputFiles(outDir));
+  return files.every((file) => present.has(file));
+}
+async function isManifestFresh(outDir, manifest, inputsHash) {
+  if (manifest === null) return false;
+  if (manifest.version !== VERSION) return false;
+  if (manifest.hash !== inputsHash) return false;
+  if (manifest.files.length === 0) return false;
+  return allOutputsExist(outDir, manifest.files);
+}
+
 // src/util/debug-log.ts
 var debugEnabled = false;
 function setCodegenDebug(enabled) {
@@ -2099,6 +2192,12 @@ function debugWarn(message) {
 // src/generate.ts
 async function generate(config, inputRoutes = []) {
   setCodegenDebug(config.debug);
+  const inputsHash = await computeInputsHash(config);
+  const manifest = await readManifest(config.codegen.outDir);
+  if (await isManifestFresh(config.codegen.outDir, manifest, inputsHash)) {
+    console.log(`[nestjs-codegen] ${config.codegen.outDir} up to date, skipped`);
+    return;
+  }
   const extensions = config.extensions ?? [];
   let routes = inputRoutes;
   const ctx = createExtensionContext(config, () => routes);
@@ -2155,21 +2254,27 @@ async function generate(config, inputRoutes = []) {
   if (extensions.length > 0) {
     const extraFiles = await collectEmittedFiles(extensions, ctx);
     for (const file of extraFiles) {
-      const dest = join12(config.codegen.outDir, file.path);
+      const dest = join13(config.codegen.outDir, file.path);
       await mkdir9(dirname2(dest), { recursive: true });
-      await writeFile9(dest, file.contents, "utf8");
+      await writeFile10(dest, file.contents, "utf8");
     }
   }
+  const outputFiles = await listOutputFiles(config.codegen.outDir);
+  await writeManifest(config.codegen.outDir, {
+    version: VERSION,
+    hash: inputsHash,
+    files: outputFiles
+  });
 }
 
 // src/watch/watcher.ts
-import { readFile as readFile3 } from "fs/promises";
-import { join as join15 } from "path";
+import { readFile as readFile4 } from "fs/promises";
+import { join as join16 } from "path";
 import chokidar from "chokidar";
 
 // src/discovery/contracts-fast.ts
-import { join as join13, resolve as resolve3 } from "path";
-import fg2 from "fast-glob";
+import { join as join14, resolve as resolve3 } from "path";
+import fg3 from "fast-glob";
 import {
   Node as Node8,
   Project as Project3
@@ -3946,7 +4051,7 @@ async function discoverContractsFast(opts) {
   const { cwd, glob, tsconfig } = opts;
   const tsconfigPath = resolveTsconfigPath(cwd, tsconfig);
   const project = createDiscoveryProject(tsconfigPath);
-  const files = await fg2(glob, { cwd, absolute: true, onlyFiles: true });
+  const files = await fg3(glob, { cwd, absolute: true, onlyFiles: true });
   for (const f of files) {
     project.addSourceFileAtPath(f);
   }
@@ -3954,7 +4059,7 @@ async function discoverContractsFast(opts) {
   return extractAllRoutes(project);
 }
 function resolveTsconfigPath(cwd, tsconfig) {
-  return tsconfig ? resolve3(tsconfig) : join13(cwd, "tsconfig.json");
+  return tsconfig ? resolve3(tsconfig) : join14(cwd, "tsconfig.json");
 }
 function createDiscoveryProject(tsconfigPath) {
   try {
@@ -4019,7 +4124,7 @@ var PersistentDiscovery = class _PersistentDiscovery {
     const project = createDiscoveryProject(tsconfigPath);
     bindDiscoveryContext(project, cwd, tsconfigPath);
     const instance = new _PersistentDiscovery(project, cwd, glob);
-    const files = await fg2(glob, { cwd, absolute: true, onlyFiles: true });
+    const files = await fg3(glob, { cwd, absolute: true, onlyFiles: true });
     for (const f of files) {
       project.addSourceFileAtPath(f);
       instance.controllerPaths.add(f);
@@ -4048,7 +4153,7 @@ var PersistentDiscovery = class _PersistentDiscovery {
       }
     }
     const globbed = new Set(
-      await fg2(this.glob, { cwd: this.cwd, absolute: true, onlyFiles: true })
+      await fg3(this.glob, { cwd: this.cwd, absolute: true, onlyFiles: true })
     );
     for (const f of globbed) {
       if (!this.controllerPaths.has(f)) {
@@ -4329,9 +4434,9 @@ function extractFromSourceFile(sourceFile, project) {
 
 // src/watch/lock-file.ts
 import { open } from "fs/promises";
-import { mkdir as mkdir10, readFile as readFile2, unlink } from "fs/promises";
-import { join as join14 } from "path";
-var LOCK_FILE = ".watcher.lock";
+import { mkdir as mkdir10, readFile as readFile3, unlink } from "fs/promises";
+import { join as join15 } from "path";
+var LOCK_FILE2 = ".watcher.lock";
 function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -4342,7 +4447,7 @@ function isProcessAlive(pid) {
 }
 async function acquireLock(outDir) {
   await mkdir10(outDir, { recursive: true });
-  const lockPath = join14(outDir, LOCK_FILE);
+  const lockPath = join15(outDir, LOCK_FILE2);
   const lockData = { pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() };
   try {
     const fd = await open(lockPath, "wx");
@@ -4352,7 +4457,7 @@ async function acquireLock(outDir) {
   } catch (err) {
     if (err.code === "EEXIST") {
       try {
-        const raw = await readFile2(lockPath, "utf8");
+        const raw = await readFile3(lockPath, "utf8");
         const existing = JSON.parse(raw);
         if (isProcessAlive(existing.pid)) return null;
         await unlink(lockPath);
@@ -4377,12 +4482,12 @@ async function acquireLock(outDir) {
 var PAGES_DEBOUNCE_MS = 150;
 var NO_OP_WATCHER = { close: async () => {
 } };
-async function watch(config, onChange) {
+async function watch(config, onChange, options = {}) {
   const lock = await acquireLock(config.codegen.outDir);
   if (lock === null) {
     let holderPid = "unknown";
     try {
-      const raw = await readFile3(join15(config.codegen.outDir, ".watcher.lock"), "utf8");
+      const raw = await readFile4(join16(config.codegen.outDir, ".watcher.lock"), "utf8");
       const data = JSON.parse(raw);
       if (data.pid !== void 0) holderPid = String(data.pid);
     } catch {
@@ -4405,22 +4510,33 @@ async function watch(config, onChange) {
     }
     return discovery;
   }
-  try {
-    const initialRoutes = (await getDiscovery()).discover();
-    lastRoutes = initialRoutes;
-    await generate(config, initialRoutes);
-  } catch (err) {
-    console.warn(
-      `[nestjs-codegen] Initial route discovery failed, falling back to pages-only: ${err instanceof Error ? err.message : String(err)}`
-    );
+  async function runInitialPass() {
     try {
-      await generate(config, lastRoutes);
-    } catch {
+      const initialRoutes = (await getDiscovery()).discover();
+      lastRoutes = initialRoutes;
+      await generate(config, initialRoutes);
+    } catch (err) {
+      console.warn(
+        `[nestjs-codegen] Initial route discovery failed, falling back to pages-only: ${err instanceof Error ? err.message : String(err)}`
+      );
+      try {
+        await generate(config, lastRoutes);
+      } catch {
+      }
     }
   }
+  if (options.deferInitialGenerate) {
+    void runInitialPass().catch((err) => {
+      console.warn(
+        `[nestjs-codegen] Background initial generate failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+  } else {
+    await runInitialPass();
+  }
   let pagesDebounceTimer;
   const pagesGlob = config.pages?.glob ?? ".nestjs-codegen-no-pages";
-  const pagesWatcher = chokidar.watch(join15(config.codegen.cwd, pagesGlob), {
+  const pagesWatcher = chokidar.watch(join16(config.codegen.cwd, pagesGlob), {
     ignoreInitial: true,
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
@@ -4447,7 +4563,7 @@ async function watch(config, onChange) {
   pagesWatcher.on("unlink", schedulePagesRegenerate);
   let contractsDebounceTimer;
   const pendingChangedPaths = /* @__PURE__ */ new Set();
-  const contractsWatcher = chokidar.watch(join15(config.codegen.cwd, config.contracts.glob), {
+  const contractsWatcher = chokidar.watch(join16(config.codegen.cwd, config.contracts.glob), {
     ignoreInitial: true,
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
@@ -4477,7 +4593,7 @@ async function watch(config, onChange) {
   contractsWatcher.on("add", (p) => scheduleContractsRegenerate(p));
   contractsWatcher.on("change", (p) => scheduleContractsRegenerate(p));
   contractsWatcher.on("unlink", (p) => scheduleContractsRegenerate(p));
-  const formsWatcher = chokidar.watch(join15(config.codegen.cwd, config.forms.watch), {
+  const formsWatcher = chokidar.watch(join16(config.codegen.cwd, config.forms.watch), {
     ignoreInitial: true,
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
@@ -4587,7 +4703,7 @@ function createChainModuleRenderer(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.11.0";
+var VERSION = "0.12.0";
 export {
   CodegenError,
   ConfigError,