@dudousxd/nestjs-codegen 0.14.1 → 0.15.0

package/dist/nest/index.d.cts

@@ -1,5 +1,6 @@
-import { DynamicModule, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
-import { U as UserConfig } from '../index-DT8SgPxp.cjs';
+import * as _nestjs_common from '@nestjs/common';
+import { DynamicModule, OnApplicationBootstrap, OnModuleDestroy, ExecutionContext } from '@nestjs/common';
+import { U as UserConfig } from '../index-CjIDPMsV.cjs';
 import 'ts-morph';
 
 /**
@@ -82,4 +83,56 @@ declare class NestjsCodegenModule {
     static forRoot(options?: CodegenModuleOptions): DynamicModule;
 }
 
-export { CODEGEN_MODULE_OPTIONS, type CodegenModuleOptions, NestjsCodegenModule, NestjsCodegenService, shouldRun };
+/**
+ * Normalize a raw query value — `string | string[] | undefined | null` (and, for
+ * back-compat with the comma-joined wire format, a comma-separated string) — into
+ * a clean `string[]`.
+ *
+ * Why this exists: Express (and therefore Nest's default query parser) hands back a
+ * **bare `string`** when a querystring key carries exactly one value (`?ids=a`), and a
+ * `string[]` only when it carries two or more (`?ids=a&ids=b`). `ParseArrayPipe` rejects
+ * the single-value form, so the *common* case (one item selected) 400s while the
+ * multi-value case passes — an inverted footgun. This helper accepts every shape:
+ *
+ * - `undefined` / `null`                 → `[]`
+ * - `'a'`            (single value)      → `['a']`
+ * - `['a', 'b']`     (repeated param)    → `['a', 'b']`
+ * - `'a,b'`          (comma-joined wire) → `['a', 'b']`  (see `@dudousxd/nestjs-client`
+ *                                          `arrayFormat: 'comma'`, the client default)
+ *
+ * Empty/whitespace-only entries are dropped. The comma-split is a compatibility fallback:
+ * once the client sends `arrayFormat: 'repeat'` (`?ids=a&ids=b`), it degrades to a no-op
+ * and only the single-value bare-string case still needs normalizing.
+ *
+ * Exported standalone so it can back a `class-transformer` `@Transform` on a DTO field
+ * (`@Transform(({ value }) => toStringList(value))`) as well as the {@link QueryList}
+ * param decorator.
+ */
+declare function toStringList(raw: unknown): string[];
+/**
+ * Resolve a `string[]` from a request's query param `key` via {@link toStringList}.
+ * The seam the {@link QueryList} decorator is built on — exported so callers can reuse
+ * the exact resolution in a bespoke `createParamDecorator`. Returns `[]` when no `key`
+ * is given (a param decorator cannot infer the target property name).
+ */
+declare function resolveQueryList(key: string | undefined, ctx: ExecutionContext): string[];
+/**
+ * Param decorator that reads an array query param safely, always yielding a clean
+ * `string[]` regardless of whether the client sent one value, many, or a comma-joined
+ * string. Use it instead of `@Query(key, ParseArrayPipe)` for *optional* array query
+ * params:
+ *
+ * ```ts
+ * @Get()
+ * list(@QueryList('baseIds') baseIds: string[]) {
+ *   // baseIds is always a clean string[] — [] when the param is absent,
+ *   // ['a'] for ?baseIds=a, ['a','b'] for ?baseIds=a&baseIds=b or ?baseIds=a,b
+ * }
+ * ```
+ *
+ * See {@link toStringList} for the exact normalization and the single-value footgun it
+ * closes.
+ */
+declare const QueryList: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+
+export { CODEGEN_MODULE_OPTIONS, type CodegenModuleOptions, NestjsCodegenModule, NestjsCodegenService, QueryList, resolveQueryList, shouldRun, toStringList };

package/dist/nest/index.d.ts

@@ -1,5 +1,6 @@
-import { DynamicModule, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
-import { U as UserConfig } from '../index-DT8SgPxp.js';
+import * as _nestjs_common from '@nestjs/common';
+import { DynamicModule, OnApplicationBootstrap, OnModuleDestroy, ExecutionContext } from '@nestjs/common';
+import { U as UserConfig } from '../index-CjIDPMsV.js';
 import 'ts-morph';
 
 /**
@@ -82,4 +83,56 @@ declare class NestjsCodegenModule {
     static forRoot(options?: CodegenModuleOptions): DynamicModule;
 }
 
-export { CODEGEN_MODULE_OPTIONS, type CodegenModuleOptions, NestjsCodegenModule, NestjsCodegenService, shouldRun };
+/**
+ * Normalize a raw query value — `string | string[] | undefined | null` (and, for
+ * back-compat with the comma-joined wire format, a comma-separated string) — into
+ * a clean `string[]`.
+ *
+ * Why this exists: Express (and therefore Nest's default query parser) hands back a
+ * **bare `string`** when a querystring key carries exactly one value (`?ids=a`), and a
+ * `string[]` only when it carries two or more (`?ids=a&ids=b`). `ParseArrayPipe` rejects
+ * the single-value form, so the *common* case (one item selected) 400s while the
+ * multi-value case passes — an inverted footgun. This helper accepts every shape:
+ *
+ * - `undefined` / `null`                 → `[]`
+ * - `'a'`            (single value)      → `['a']`
+ * - `['a', 'b']`     (repeated param)    → `['a', 'b']`
+ * - `'a,b'`          (comma-joined wire) → `['a', 'b']`  (see `@dudousxd/nestjs-client`
+ *                                          `arrayFormat: 'comma'`, the client default)
+ *
+ * Empty/whitespace-only entries are dropped. The comma-split is a compatibility fallback:
+ * once the client sends `arrayFormat: 'repeat'` (`?ids=a&ids=b`), it degrades to a no-op
+ * and only the single-value bare-string case still needs normalizing.
+ *
+ * Exported standalone so it can back a `class-transformer` `@Transform` on a DTO field
+ * (`@Transform(({ value }) => toStringList(value))`) as well as the {@link QueryList}
+ * param decorator.
+ */
+declare function toStringList(raw: unknown): string[];
+/**
+ * Resolve a `string[]` from a request's query param `key` via {@link toStringList}.
+ * The seam the {@link QueryList} decorator is built on — exported so callers can reuse
+ * the exact resolution in a bespoke `createParamDecorator`. Returns `[]` when no `key`
+ * is given (a param decorator cannot infer the target property name).
+ */
+declare function resolveQueryList(key: string | undefined, ctx: ExecutionContext): string[];
+/**
+ * Param decorator that reads an array query param safely, always yielding a clean
+ * `string[]` regardless of whether the client sent one value, many, or a comma-joined
+ * string. Use it instead of `@Query(key, ParseArrayPipe)` for *optional* array query
+ * params:
+ *
+ * ```ts
+ * @Get()
+ * list(@QueryList('baseIds') baseIds: string[]) {
+ *   // baseIds is always a clean string[] — [] when the param is absent,
+ *   // ['a'] for ?baseIds=a, ['a','b'] for ?baseIds=a&baseIds=b or ?baseIds=a,b
+ * }
+ * ```
+ *
+ * See {@link toStringList} for the exact normalization and the single-value footgun it
+ * closes.
+ */
+declare const QueryList: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+
+export { CODEGEN_MODULE_OPTIONS, type CodegenModuleOptions, NestjsCodegenModule, NestjsCodegenService, QueryList, resolveQueryList, shouldRun, toStringList };

package/dist/nest/index.js

@@ -702,6 +702,9 @@ function buildErrorType(c) {
   }
   return c.contractSource.error ?? "unknown";
 }
+function filterFieldLiterals(fields) {
+  return fields?.length ? fields.map((f) => JSON.stringify(f)) : [];
+}
 function emitRouterTypeBlock(tree, indent, outDir, serialization) {
   const pad = " ".repeat(indent);
   const lines = [];
@@ -728,7 +731,8 @@ function emitRouterTypeBlock(tree, indent, outDir, serialization) {
       const params = buildParamsType(c.params);
       const safeMethod = JSON.stringify(method);
       const safeUrl = JSON.stringify(c.path);
-      const filterFields = c.contractSource.filterFields?.length ? c.contractSource.filterFields.map((f) => JSON.stringify(f)).join(" | ") : "never";
+      const filterLiterals = filterFieldLiterals(c.contractSource.filterFields);
+      const filterFields = filterLiterals.length ? filterLiterals.join(" | ") : "never";
       const stream = c.contractSource.stream ? "true" : "false";
       const binary = c.contractSource.binaryResponse ? "true" : "false";
       lines.push(
@@ -768,6 +772,7 @@ function buildRequestModel(c) {
   const TA = buildRouterTypeAccess(c.name);
   const withParams = hasPathParams(c.params);
   const { isGet, isQuery, hasBody, hasQuery } = requestShape(c.route);
+  const filterLiterals = filterFieldLiterals(c.contractSource.filterFields);
   const fields = [];
   if (withParams) fields.push(`params: ${TA}['params']`);
   if (hasQuery) fields.push(`query?: ${TA}['query']`);
@@ -797,7 +802,12 @@ function buildRequestModel(c) {
     // (`[name]` rather than `[name, undefined]`) so the bare `.queryKey()` is a
     // clean prefix that partial-matches every parametrized variant — making it
     // directly usable for `invalidateQueries`.
-    queryKeyExpr: `(input === undefined ? [${flat}] as const : [${flat}, input] as const)`
+    queryKeyExpr: `(input === undefined ? [${flat}] as const : [${flat}, input] as const)`,
+    // Runtime counterpart to the type-level `filterFields` union: the same
+    // discovered field list, emitted as a literal `[...] as const` so apps can
+    // validate a dynamic/user-supplied field string with `isFilterField(...)`
+    // instead of casting. Omitted for routes with no filter.
+    ...filterLiterals.length ? { filterFieldsExpr: `[${filterLiterals.join(", ")}] as const` } : {}
   };
 }
 function renderFetcherRequest(req, binaryResponse) {
@@ -832,9 +842,24 @@ function emitReqHelper() {
     ""
   ];
 }
+function emitFilterFieldGuard() {
+  return [
+    "/** Runtime guard: narrows `value` to one of the leaf's `filterFields` (a `readonly K[] as const`), so a dynamic field string can be passed to `.where()` without a cast. */",
+    "export function isFilterField<const K extends string>(",
+    "  fields: readonly K[],",
+    "  value: string,",
+    "): value is K {",
+    "  return (fields as readonly string[]).includes(value);",
+    "}",
+    ""
+  ];
+}
 function renderLeaf(pad, objKey, req, requestExpr, members, streamExpr) {
   const lines = [`${pad}${objKey}: (input?: ${req.inputType}) => ({`];
   lines.push(`${pad}  ...__req<${req.responseType}>(() => ${requestExpr}),`);
+  if (req.filterFieldsExpr) {
+    lines.push(`${pad}  filterFields: ${req.filterFieldsExpr},`);
+  }
   if (streamExpr) {
     lines.push(`${pad}  stream: () => ${streamExpr},`);
   }
@@ -1106,6 +1131,9 @@ function buildApiFile(routes, outDir, opts = {}) {
   lines.push("};");
   lines.push("");
   lines.push(...emitReqHelper());
+  if (contracted.some((r) => r.contract?.contractSource.filterFields?.length)) {
+    lines.push(...emitFilterFieldGuard());
+  }
   lines.push("export function createApi(fetcher: Fetcher) {");
   lines.push("  return {");
   lines.push(
@@ -2099,8 +2127,9 @@ function debugWarn(message) {
 }
 
 // src/generate.ts
-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.`;
+function driftGuardMessage(outDir, previousEntryPoint, currentEntryPoint, differingKeys) {
+  const differ = differingKeys.length > 0 ? `their resolved configs differ at: ${differingKeys.map((key) => `\`${key}\``).join(", ")}` : "their resolved configs differ (re-run after this generate records per-key hashes to see which keys)";
+  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 ${differ}. 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);
@@ -2111,9 +2140,17 @@ async function generate(config, inputRoutes = [], entryPoint = "cli") {
     return;
   }
   const configHash = computeConfigHash(config);
+  const configKeyHashes = computeConfigKeyHashes(config);
   if (config.driftGuard && manifest?.entryPoint && manifest.entryPoint !== entryPoint && manifest.configHash && manifest.configHash !== configHash) {
     throw new DriftGuardError(
-      driftGuardMessage(config.codegen.outDir, manifest.entryPoint, entryPoint)
+      driftGuardMessage(
+        config.codegen.outDir,
+        manifest.entryPoint,
+        entryPoint,
+        // A pre-key-hash manifest can't tell us WHICH keys differ — pass none
+        // rather than diffing against {} (which would name every key).
+        manifest.configKeyHashes ? diffConfigKeyHashes(manifest.configKeyHashes, configKeyHashes) : []
+      )
     );
   }
   const extensions = config.extensions ?? [];
@@ -2183,6 +2220,7 @@ async function generate(config, inputRoutes = [], entryPoint = "cli") {
     hash: inputsHash,
     entryPoint,
     configHash,
+    configKeyHashes,
     files: outputFiles
   });
 }
@@ -4612,7 +4650,7 @@ async function watch(config, onChange, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.14.1";
+var VERSION = "0.15.0";
 
 // src/generate-manifest.ts
 var MANIFEST_FILE = ".codegen-manifest.json";
@@ -4633,19 +4671,41 @@ function isManifestShape(value) {
   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 (candidate.configKeyHashes !== void 0 && !isStringRecord(candidate.configKeyHashes)) {
+    return false;
+  }
   if (!Array.isArray(candidate.files)) return false;
   return candidate.files.every((entry) => typeof entry === "string");
 }
+function isStringRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((entry) => typeof entry === "string");
+}
 function serializeConfig(config) {
+  return serializeConfigValue(config, `unserializable:${config.codegen.outDir}`);
+}
+function serializeConfigValue(value, unserializableMarker) {
   try {
-    return JSON.stringify(config, (_key, value) => {
-      if (typeof value === "function") return `[fn:${value.name}]${value.toString()}`;
-      return value;
+    return JSON.stringify(value, (_key, entry) => {
+      if (typeof entry === "function") return `[fn:${entry.name}]`;
+      return entry;
     });
   } catch {
-    return `unserializable:${config.codegen.outDir}:${config.contracts.glob}`;
+    return unserializableMarker;
   }
 }
+function computeConfigKeyHashes(config) {
+  const hashes = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (value === void 0) continue;
+    hashes[key] = createHash("sha256").update(serializeConfigValue(value, `unserializable:${key}`)).digest("hex");
+  }
+  return hashes;
+}
+function diffConfigKeyHashes(previous, current) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(previous), ...Object.keys(current)]);
+  return [...keys].filter((key) => previous[key] !== current[key]).sort();
+}
 async function discoverInputFiles(config) {
   const globs = [config.contracts.glob, config.forms.watch];
   if (config.pages) globs.push(config.pages.glob);
@@ -4680,6 +4740,7 @@ async function readManifest(outDir) {
       hash: parsed.hash,
       ...parsed.entryPoint ? { entryPoint: parsed.entryPoint } : {},
       ...parsed.configHash ? { configHash: parsed.configHash } : {},
+      ...parsed.configKeyHashes ? { configKeyHashes: parsed.configKeyHashes } : {},
       files: parsed.files
     };
   } catch {
@@ -4789,10 +4850,26 @@ var NestjsCodegenModule = class {
 NestjsCodegenModule = __decorateClass([
   Module({})
 ], NestjsCodegenModule);
+
+// src/nest/query-list.ts
+import { createParamDecorator } from "@nestjs/common";
+function toStringList(raw) {
+  if (raw === void 0 || raw === null) return [];
+  const arr = Array.isArray(raw) ? raw : String(raw).split(",");
+  return arr.map((entry) => String(entry).trim()).filter((entry) => entry.length > 0);
+}
+function resolveQueryList(key, ctx) {
+  const request = ctx.switchToHttp().getRequest();
+  return toStringList(key ? request.query?.[key] : void 0);
+}
+var QueryList = createParamDecorator(resolveQueryList);
 export {
   CODEGEN_MODULE_OPTIONS,
   NestjsCodegenModule,
   NestjsCodegenService,
-  shouldRun
+  QueryList,
+  resolveQueryList,
+  shouldRun,
+  toStringList
 };
 //# sourceMappingURL=index.js.map