@dudousxd/nestjs-codegen 0.13.1 → 0.14.0

package/dist/cli/main.js

@@ -146,7 +146,8 @@ function applyDefaults(userConfig, cwd) {
       fileName: userConfig.mocks?.fileName ?? "mocks.ts",
       seed: userConfig.mocks?.seed ?? 1,
       baseUrl: userConfig.mocks?.baseUrl ?? ""
-    }
+    },
+    driftGuard: userConfig.driftGuard ?? true
   };
 }
 async function loadConfig(cwd) {
@@ -606,7 +607,7 @@ async function collectEmittedFiles(extensions, ctx) {
 function requestShape(route) {
   const cs = route.contract?.contractSource;
   const isGet = route.method.toUpperCase() === "GET";
-  const isQuery = isGet || !!cs?.filterFields?.length;
+  const isQuery = isGet || !!cs?.filterFields?.length || !!cs?.asQuery;
   const hasBody = !!cs?.bodyRef || cs?.body != null && cs.body !== "never";
   const hasQuery = isGet || !!cs?.queryRef || cs?.query != null && cs.query !== "never";
   return { isGet, isQuery, hasBody, hasQuery };
@@ -713,6 +714,7 @@ function emitFilterQueryType(c) {
   return `import('@dudousxd/nestjs-filter-client').TypedFilterQuery<${emitFilterQueryTypeArgs(c)}>`;
 }
 function buildResponseType(c, outDir, serialization) {
+  if (c.contractSource.binaryResponse) return "RawResponse<Blob>";
   const raw = rawResponseType(c, outDir);
   return serialization === "json" ? `Jsonify<${raw}>` : raw;
 }
@@ -767,8 +769,9 @@ function emitRouterTypeBlock(tree, indent, outDir, serialization) {
       const safeUrl = JSON.stringify(c.path);
       const filterFields = c.contractSource.filterFields?.length ? c.contractSource.filterFields.map((f) => JSON.stringify(f)).join(" | ") : "never";
       const stream = c.contractSource.stream ? "true" : "false";
+      const binary = c.contractSource.binaryResponse ? "true" : "false";
       lines.push(
-        `${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response}; error: ${error}; filterFields: ${filterFields}; stream: ${stream} };`
+        `${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response}; error: ${error}; filterFields: ${filterFields}; stream: ${stream}; binary: ${binary} };`
       );
     } else {
       lines.push(`${pad}${objKey}: {`);
@@ -814,6 +817,9 @@ function buildRequestModel(c) {
   if (hasQuery) optsParts.push("query: input?.query as Record<string, unknown> | undefined");
   if (hasBody) optsParts.push("body: input?.body");
   if (hasBody && c.contractSource.multipart) optsParts.push("multipart: true");
+  if (c.contractSource.binaryResponse && m !== "get") {
+    optsParts.unshift(`method: ${JSON.stringify(m.toUpperCase())}`);
+  }
   const optsExpr = optsParts.length ? `{ ${optsParts.join(", ")} }` : "{}";
   return {
     routeName: c.name,
@@ -833,7 +839,8 @@ function buildRequestModel(c) {
     queryKeyExpr: `(input === undefined ? [${flat}] as const : [${flat}, input] as const)`
   };
 }
-function renderFetcherRequest(req) {
+function renderFetcherRequest(req, binaryResponse) {
+  if (binaryResponse) return `fetcher.fetchBlob(${req.urlExpr}, ${req.optsExpr})`;
   return `fetcher.${req.method}<${req.responseType}>(${req.urlExpr}, ${req.optsExpr})`;
 }
 function emitReqHelper() {
@@ -894,7 +901,7 @@ function emitApiObjectBlock(tree, indent, p) {
     const leaf = {
       route: node.route,
       request: req,
-      requestExpr: renderFetcherRequest(req)
+      requestExpr: renderFetcherRequest(req, node.contractSource.binaryResponse === true)
     };
     const owned = /* @__PURE__ */ new Map();
     if (p.layer) {
@@ -954,6 +961,8 @@ var ROUTE_NAMESPACE = [
   '  export type FilterFields<K extends string> = ResolveByName<K, "filterFields">;',
   "  /** The streamed element type of an `@Sse()`/streaming route \u2014 the type yielded by its `stream()` AsyncIterable. */",
   '  export type Stream<K extends string> = ResolveByName<K, "response">;',
+  "  /** True for a binary/blob route (`StreamableFile`/`Buffer` handler return type). */",
+  '  export type Binary<K extends string> = ResolveByName<K, "binary">;',
   "  export type Request<K extends string> = {",
   "    body: Body<K>;",
   "    query: Query<K>;",
@@ -971,6 +980,7 @@ var PATH_NAMESPACE = [
   '  export type Error<M extends string, U extends string> = ResolveByPath<M, U, "error">;',
   '  export type FilterFields<M extends string, U extends string> = ResolveByPath<M, U, "filterFields">;',
   '  export type Stream<M extends string, U extends string> = ResolveByPath<M, U, "response">;',
+  '  export type Binary<M extends string, U extends string> = ResolveByPath<M, U, "binary">;',
   "}",
   ""
 ];
@@ -983,6 +993,7 @@ var EMPTY_ROUTE_NAMESPACE = [
   "  export type Error<K extends string> = never;",
   "  export type FilterFields<K extends string> = never;",
   "  export type Stream<K extends string> = never;",
+  "  export type Binary<K extends string> = never;",
   "  export type Request<K extends string> = { body: never; query: never; params: never };",
   "}",
   ""
@@ -996,6 +1007,7 @@ var EMPTY_PATH_NAMESPACE = [
   "  export type Error<M extends string, U extends string> = never;",
   "  export type FilterFields<M extends string, U extends string> = never;",
   "  export type Stream<M extends string, U extends string> = never;",
+  "  export type Binary<M extends string, U extends string> = never;",
   "}",
   ""
 ];
@@ -1061,6 +1073,9 @@ function buildApiFile(routes, outDir, opts = {}) {
   if (serialization === "json" && contracted.length > 0) {
     lines.push(`import type { Jsonify } from '${runtimeImport}';`);
   }
+  if (contracted.some((r) => r.contract?.contractSource.binaryResponse)) {
+    lines.push(`import type { RawResponse } from '${runtimeImport}';`);
+  }
   if (importsByFile.size > 0 && outDir) {
     lines.push("");
     const emittedNames = /* @__PURE__ */ new Set();
@@ -1097,6 +1112,12 @@ function buildApiFile(routes, outDir, opts = {}) {
     lines.push("");
     lines.push(...EMPTY_ROUTE_NAMESPACE);
     lines.push(...EMPTY_PATH_NAMESPACE);
+    for (const ext of headerExts) {
+      const statements = ext.apiHeader?.(ctx)?.statements;
+      if (statements?.length) {
+        lines.push(...statements, "");
+      }
+    }
     return lines.join("\n");
   }
   const tree = /* @__PURE__ */ new Map();
@@ -2114,11 +2135,22 @@ 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";
+var DriftGuardError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DriftGuardError";
+  }
+};
+function isEntryPoint(value) {
+  return value === "cli" || value === "module";
+}
 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 (candidate.entryPoint !== void 0 && !isEntryPoint(candidate.entryPoint)) return false;
+  if (candidate.configHash !== void 0 && typeof candidate.configHash !== "string") return false;
   if (!Array.isArray(candidate.files)) return false;
   return candidate.files.every((entry) => typeof entry === "string");
 }
@@ -2161,11 +2193,20 @@ async function readManifest(outDir) {
     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 };
+    return {
+      version: parsed.version,
+      hash: parsed.hash,
+      ...parsed.entryPoint ? { entryPoint: parsed.entryPoint } : {},
+      ...parsed.configHash ? { configHash: parsed.configHash } : {},
+      files: parsed.files
+    };
   } catch {
     return null;
   }
 }
+function computeConfigHash(config) {
+  return createHash("sha256").update(serializeConfig(config)).digest("hex");
+}
 async function writeManifest(outDir, manifest) {
   await writeFile9(join12(outDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
@@ -2210,7 +2251,10 @@ function debugWarn(message) {
 }
 
 // src/generate.ts
-async function generate(config, inputRoutes = []) {
+function driftGuardMessage(outDir, previousEntryPoint, currentEntryPoint) {
+  return `[nestjs-codegen] Config drift detected in "${outDir}": the last generate ran from the "${previousEntryPoint}" entry point, this run is from the "${currentEntryPoint}" entry point, and their resolved configs differ (e.g. \`serialization: "json"\` vs \`"superjson"\`). Both entry points must read the SAME config \u2014 export a shared config object (e.g. codegen.config.ts) and import it from BOTH nestjs-codegen.config.ts (CLI) and NestjsCodegenModule.forRoot() (Nest module), or set \`driftGuard: false\` on either config to opt out of this check.`;
+}
+async function generate(config, inputRoutes = [], entryPoint = "cli") {
   setCodegenDebug(config.debug);
   const inputsHash = await computeInputsHash(config);
   const manifest = await readManifest(config.codegen.outDir);
@@ -2218,6 +2262,12 @@ async function generate(config, inputRoutes = []) {
     console.log(`[nestjs-codegen] ${config.codegen.outDir} up to date, skipped`);
     return;
   }
+  const configHash = computeConfigHash(config);
+  if (config.driftGuard && manifest?.entryPoint && manifest.entryPoint !== entryPoint && manifest.configHash && manifest.configHash !== configHash) {
+    throw new DriftGuardError(
+      driftGuardMessage(config.codegen.outDir, manifest.entryPoint, entryPoint)
+    );
+  }
   const extensions = config.extensions ?? [];
   let routes = inputRoutes;
   const ctx = createExtensionContext(config, () => routes);
@@ -2283,6 +2333,8 @@ async function generate(config, inputRoutes = []) {
   await writeManifest(config.codegen.outDir, {
     version: VERSION,
     hash: inputsHash,
+    entryPoint,
+    configHash,
     files: outputFiles
   });
 }
@@ -3587,6 +3639,19 @@ function resolveTypeNodeToString(typeNode, sourceFile, project, depth, subst = /
     dbg("unresolvable type:", name, "in", sourceFile.getFilePath());
     return "unknown";
   }
+  if (Node6.isTypeLiteral(typeNode)) {
+    const members = [];
+    for (const member of typeNode.getMembers()) {
+      if (Node6.isPropertySignature(member)) {
+        const memberTypeNode = member.getTypeNode();
+        const memberType = memberTypeNode ? resolveTypeNodeToString(memberTypeNode, sourceFile, project, depth, subst) : "unknown";
+        members.push(`${member.getName()}${member.hasQuestionToken() ? "?" : ""}: ${memberType}`);
+      } else {
+        members.push(member.getText());
+      }
+    }
+    return members.length > 0 ? `{ ${members.join("; ")} }` : "{}";
+  }
   const kind = typeNode.getKind();
   if (kind === SyntaxKind3.StringKeyword) return "string";
   if (kind === SyntaxKind3.NumberKeyword) return "number";
@@ -3859,6 +3924,14 @@ function resolveBodyQueryResponseRef(typeNode, sourceFile, project) {
 var STREAM_CONTAINERS = /* @__PURE__ */ new Set(["Observable", "AsyncIterable", "AsyncIterableIterator"]);
 var STREAM_CONTAINERS_GENERATOR = /* @__PURE__ */ new Set(["AsyncGenerator"]);
 var STREAM_ENVELOPES = /* @__PURE__ */ new Set(["MessageEvent", "MessageEventLike"]);
+var BINARY_RESPONSE_TYPES = /* @__PURE__ */ new Set(["StreamableFile", "Buffer"]);
+function detectBinaryResponse(method) {
+  const node = unwrapNamedContainer(method.getReturnTypeNode(), /* @__PURE__ */ new Set(["Promise"]));
+  if (!node || !Node6.isTypeReference(node)) return false;
+  const typeName = node.getTypeName();
+  const name = Node6.isIdentifier(typeName) ? typeName.getText() : "";
+  return BINARY_RESPONSE_TYPES.has(name);
+}
 function detectStreamElement(method) {
   const hasSse = method.getDecorators().some((d) => d.getName() === "Sse");
   let node = method.getReturnTypeNode();
@@ -3879,6 +3952,9 @@ function streamContainerElement(node) {
   }
   return null;
 }
+function hasAsQueryDecorator(method) {
+  return method.getDecorators().some((d) => d.getName() === "AsQuery");
+}
 function unwrapNamedContainer(node, names) {
   if (!node || !Node6.isTypeReference(node)) return node;
   const typeName = node.getTypeName();
@@ -3896,6 +3972,8 @@ function extractDtoContract(method, sourceFile, project) {
   const multipartBody = uploads.fields ? `{ ${uploads.fields} }` : null;
   const streamElement = detectStreamElement(method);
   const isStream = streamElement !== null;
+  const binaryResponse = detectBinaryResponse(method);
+  const asQuery = hasAsQueryDecorator(method);
   if (filterInfo && filterInfo.source === "body") {
     const bodyType = "import('@dudousxd/nestjs-filter-client').FilterQueryResult";
     body = body ?? bodyType;
@@ -3903,7 +3981,7 @@ function extractDtoContract(method, sourceFile, project) {
   const paramsType = extractParamsType(method, sourceFile, project);
   const response = isStream ? resolveTypeNodeToString(streamElement, sourceFile, project, 3) : extractResponseType(method, sourceFile, project);
   const errorInfo = extractErrorType(method, sourceFile, project);
-  if (body === null && query === null && paramsType === null && response === "unknown" && errorInfo === null && filterInfo === null && !isStream && !uploads.multipart) {
+  if (body === null && query === null && paramsType === null && response === "unknown" && errorInfo === null && filterInfo === null && !isStream && !uploads.multipart && !binaryResponse && !asQuery) {
     return null;
   }
   let bodyRef = null;
@@ -3978,7 +4056,9 @@ function extractDtoContract(method, sourceFile, project) {
     querySchema,
     stream: isStream,
     multipart: uploads.multipart,
-    multipartBody
+    multipartBody,
+    binaryResponse,
+    asQuery
   };
 }
 function resolveParamClass(method, decoratorName, sourceFile, project) {
@@ -4465,7 +4545,9 @@ function extractDtoRoute(args) {
       querySchema: dtoContract?.querySchema ?? null,
       stream: dtoContract?.stream ?? false,
       multipart: dtoContract?.multipart ?? false,
-      multipartBody: dtoContract?.multipartBody ?? null
+      multipartBody: dtoContract?.multipartBody ?? null,
+      binaryResponse: dtoContract?.binaryResponse ?? false,
+      asQuery: dtoContract?.asQuery ?? false
     }
   });
 }
@@ -4558,6 +4640,7 @@ var PAGES_DEBOUNCE_MS = 150;
 var NO_OP_WATCHER = { close: async () => {
 } };
 async function watch(config, onChange, options = {}) {
+  const entryPoint = options.entryPoint ?? "cli";
   const lock = await acquireLock(config.codegen.outDir);
   if (lock === null) {
     let holderPid = "unknown";
@@ -4589,13 +4672,17 @@ async function watch(config, onChange, options = {}) {
     try {
       const initialRoutes = (await getDiscovery()).discover();
       lastRoutes = initialRoutes;
-      await generate(config, initialRoutes);
+      await generate(config, initialRoutes, entryPoint);
     } catch (err) {
+      if (err instanceof DriftGuardError) {
+        console.error(err.message);
+        return;
+      }
       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);
+        await generate(config, lastRoutes, entryPoint);
       } catch {
       }
     }
@@ -4623,7 +4710,7 @@ async function watch(config, onChange, options = {}) {
     pagesDebounceTimer = setTimeout(async () => {
       pagesDebounceTimer = void 0;
       try {
-        await generate(config, lastRoutes);
+        await generate(config, lastRoutes, entryPoint);
       } catch (err) {
         console.error(
           "[nestjs-codegen] Pages generation failed:",
@@ -4655,7 +4742,7 @@ async function watch(config, onChange, options = {}) {
       try {
         const routes = await (await getDiscovery()).rediscover(changed);
         lastRoutes = routes;
-        await generate(config, routes);
+        await generate(config, routes, entryPoint);
       } catch (err) {
         console.error(
           "[nestjs-codegen] Contracts generation failed:",
@@ -4695,14 +4782,14 @@ async function watch(config, onChange, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.13.1";
+var VERSION = "0.14.0";
 
 // src/cli/codegen.ts
 async function runCodegen(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const config = await loadConfig(cwd);
   if (opts.watch) {
-    const watcher = await watch(config);
+    const watcher = await watch(config, void 0, { entryPoint: "cli" });
     await new Promise((resolve4) => {
       function onSignal() {
         watcher.close().then(resolve4).catch(resolve4);
@@ -4717,7 +4804,7 @@ async function runCodegen(opts = {}) {
     glob: config.contracts.glob,
     ...config.app?.tsconfig ? { tsconfig: config.app.tsconfig } : {}
   });
-  await generate(config, routes);
+  await generate(config, routes, "cli");
   console.log("\u2713 Codegen generated artifacts in", config.codegen.outDir);
 }