@dudousxd/nestjs-codegen 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @dudousxd/nestjs-codegen
 
+## 0.14.0
+
+### Minor Changes
+
+- fc78a39: feat: binary (blob) response mode, `@AsQuery()` marker, CLI↔module config-drift guard, and a `handleQuery` TanStack helper.
+
+  - **Binary (blob) response mode.** A handler returning NestJS `StreamableFile` or Node `Buffer`
+    (including `Promise<StreamableFile>`) is now discovered as `binaryResponse: true` and emitted
+    with `response: RawResponse<Blob>` (never `Jsonify<...>`) — the leaf issues its request via
+    `fetcher.fetchBlob(...)` instead of the verb method, so callers get `{ data, status, headers }`
+    and can read `content-disposition` etc. Works on any HTTP method (`fetchBlob` already accepted
+    a `method` opt); a non-GET binary route passes it explicitly since `fetchBlob` defaults to GET.
+    `Observable`/`ReadableStream` handlers are unaffected — they stay on the existing SSE/stream
+    path. Each `ApiRouter` leaf now also carries a `binary` flag (`Route.Binary<K>` /
+    `Path.Binary<M, U>` type helpers), mirroring `stream`.
+  - **`@AsQuery()` marker** (new `@dudousxd/nestjs-codegen/markers` subpath — zero-import, runtime
+    no-op). Marks a non-GET route whose semantics are a read (e.g. a POST with a query-shaped
+    payload) so codegen emits `queryOptions` for it, exactly like a GET or a filter-search route.
+  - **CLI↔module config-drift guard.** The CLI (`nestjs-codegen.config.ts`) and the Nest module
+    (`NestjsCodegenModule.forRoot()`) can target the same `outDir` from independently-resolved
+    configs; if they genuinely differ (e.g. `serialization` `'json'` vs `'superjson'`), each run
+    used to silently overwrite the other's `api.ts` shape. `generate()` now throws a
+    `DriftGuardError` _before writing anything_ when the manifest's `entryPoint` differs from the
+    current run's AND the resolved configs' hashes differ — naming both entry points and
+    instructing how to fix it (share one config object, or set `driftGuard: false`). Same entry
+    point (a normal config edit) or same config across entry points both proceed as before.
+  - **TanStack: `handleQuery` helper**, emitted into `api.ts` whenever the TanStack layer is
+    active. Wraps any `{ queryKey, fetch }`-shaped handle (a POST-as-query handle, or a runtime
+    pick between two different handles) into a plain `{ queryKey, queryFn }` pair — solves the
+    useQuery-overload break from spreading a ternary of `queryOptions()` calls. Also: binary GET
+    routes get `queryOptions` but never `infiniteQueryOptions` (a download isn't paginated data).
+
+## 0.13.2
+
+### Patch Changes
+
+- 889af1f: Resolve the members of an inline object-literal type (`{ a: Foo; b: Bar }`) in response/stream types instead of emitting the node's raw text. A named type nested in an object literal — most commonly an SSE payload's `Observable<{ data: SomeType }>`, where `SomeType` is imported from another package — was previously copied verbatim, leaving a bare, unimported identifier that is undefined in the generated file. Each member's type is now resolved (expanded inline, or reduced to `unknown` when unresolvable) like any other named reference.
+
 ## 0.13.1
 
 ### Patch Changes

package/dist/cli/main.cjs

@@ -180,7 +180,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) {
@@ -640,7 +641,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 };
@@ -747,6 +748,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;
 }
@@ -801,8 +803,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}: {`);
@@ -848,6 +851,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,
@@ -867,7 +873,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() {
@@ -928,7 +935,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) {
@@ -988,6 +995,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>;",
@@ -1005,6 +1014,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">;',
   "}",
   ""
 ];
@@ -1017,6 +1027,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 };",
   "}",
   ""
@@ -1030,6 +1041,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;",
   "}",
   ""
 ];
@@ -1095,6 +1107,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();
@@ -1131,6 +1146,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();
@@ -2148,11 +2169,22 @@ var import_node_path12 = require("path");
 var import_fast_glob2 = __toESM(require("fast-glob"), 1);
 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");
 }
@@ -2195,11 +2227,20 @@ async function readManifest(outDir) {
     const raw = await (0, import_promises11.readFile)((0, import_node_path12.join)(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 (0, import_node_crypto.createHash)("sha256").update(serializeConfig(config)).digest("hex");
+}
 async function writeManifest(outDir, manifest) {
   await (0, import_promises11.writeFile)((0, import_node_path12.join)(outDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
@@ -2244,7 +2285,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);
@@ -2252,6 +2296,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);
@@ -2317,6 +2367,8 @@ async function generate(config, inputRoutes = []) {
   await writeManifest(config.codegen.outDir, {
     version: VERSION,
     hash: inputsHash,
+    entryPoint,
+    configHash,
     files: outputFiles
   });
 }
@@ -3606,6 +3658,19 @@ function resolveTypeNodeToString(typeNode, sourceFile, project, depth, subst = /
     dbg("unresolvable type:", name, "in", sourceFile.getFilePath());
     return "unknown";
   }
+  if (import_ts_morph7.Node.isTypeLiteral(typeNode)) {
+    const members = [];
+    for (const member of typeNode.getMembers()) {
+      if (import_ts_morph7.Node.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 === import_ts_morph7.SyntaxKind.StringKeyword) return "string";
   if (kind === import_ts_morph7.SyntaxKind.NumberKeyword) return "number";
@@ -3878,6 +3943,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 || !import_ts_morph7.Node.isTypeReference(node)) return false;
+  const typeName = node.getTypeName();
+  const name = import_ts_morph7.Node.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();
@@ -3898,6 +3971,9 @@ function streamContainerElement(node) {
   }
   return null;
 }
+function hasAsQueryDecorator(method) {
+  return method.getDecorators().some((d) => d.getName() === "AsQuery");
+}
 function unwrapNamedContainer(node, names) {
   if (!node || !import_ts_morph7.Node.isTypeReference(node)) return node;
   const typeName = node.getTypeName();
@@ -3915,6 +3991,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;
@@ -3922,7 +4000,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;
@@ -3997,7 +4075,9 @@ function extractDtoContract(method, sourceFile, project) {
     querySchema,
     stream: isStream,
     multipart: uploads.multipart,
-    multipartBody
+    multipartBody,
+    binaryResponse,
+    asQuery
   };
 }
 function resolveParamClass(method, decoratorName, sourceFile, project) {
@@ -4484,7 +4564,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
     }
   });
 }
@@ -4577,6 +4659,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";
@@ -4608,13 +4691,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 {
       }
     }
@@ -4642,7 +4729,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:",
@@ -4674,7 +4761,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:",
@@ -4714,14 +4801,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);
@@ -4736,7 +4823,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);
 }