@dudousxd/nestjs-codegen 0.4.0 → 0.5.0

package/dist/index.js

@@ -131,6 +131,19 @@ function applyDefaults(userConfig, cwd) {
       enabled: userConfig.forms?.enabled ?? true,
       watch: userConfig.forms?.watch ?? "src/**/*.dto.ts",
       zodImport: userConfig.forms?.zodImport ?? "zod"
+    },
+    openapi: {
+      enabled: userConfig.openapi?.enabled ?? false,
+      fileName: userConfig.openapi?.fileName ?? "openapi.json",
+      title: userConfig.openapi?.title ?? "NestJS API",
+      version: userConfig.openapi?.version ?? "1.0.0",
+      description: userConfig.openapi?.description ?? null
+    },
+    mocks: {
+      enabled: userConfig.mocks?.enabled ?? false,
+      fileName: userConfig.mocks?.fileName ?? "mocks.ts",
+      seed: userConfig.mocks?.seed ?? 1,
+      baseUrl: userConfig.mocks?.baseUrl ?? ""
     }
   };
 }
@@ -168,8 +181,8 @@ Run \`nestjs-codegen init\` to create a starter config.`
 }
 
 // src/generate.ts
-import { mkdir as mkdir7, writeFile as writeFile7 } from "fs/promises";
-import { dirname as dirname2, join as join10 } from "path";
+import { mkdir as mkdir9, writeFile as writeFile9 } from "fs/promises";
+import { dirname as dirname2, join as join12 } from "path";
 
 // src/discovery/pages.ts
 import { readFile } from "fs/promises";
@@ -698,17 +711,28 @@ function emitFilterQueryType(c) {
   return `import('@dudousxd/nestjs-filter-client').TypedFilterQuery<${emitFilterQueryTypeArgs(c)}>`;
 }
 function buildResponseType(c, outDir) {
+  const respRef = c.contractSource.responseRef;
+  if (c.contractSource.stream) {
+    if (respRef) return respRef.isArray ? `Array<${respRef.name}>` : respRef.name;
+    return c.contractSource.response;
+  }
   if (c.controllerRef) {
     let relPath = relative3(outDir, c.controllerRef.filePath).replace(/\.ts$/, "");
     if (!relPath.startsWith(".")) relPath = `./${relPath}`;
     return `Awaited<ReturnType<import('${relPath}').${c.controllerRef.className}['${c.controllerRef.methodName}']>>`;
   }
-  const respRef = c.contractSource.responseRef;
   if (respRef) {
     return respRef.isArray ? `Array<${respRef.name}>` : respRef.name;
   }
   return c.contractSource.response;
 }
+function buildErrorType(c) {
+  const errRef = c.contractSource.errorRef;
+  if (errRef) {
+    return errRef.isArray ? `Array<${errRef.name}>` : errRef.name;
+  }
+  return c.contractSource.error ?? "unknown";
+}
 function emitRouterTypeBlock(tree, indent, outDir) {
   const pad = " ".repeat(indent);
   const lines = [];
@@ -723,12 +747,14 @@ function emitRouterTypeBlock(tree, indent, outDir) {
       const bodyRef = c.contractSource.bodyRef;
       const body = method === "GET" ? "never" : bodyRef ? bodyRef.isArray ? `Array<${bodyRef.name}>` : bodyRef.name : c.contractSource.body ?? "never";
       const response = buildResponseType(c, outDir);
+      const error = buildErrorType(c);
       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 stream = c.contractSource.stream ? "true" : "false";
       lines.push(
-        `${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response}; filterFields: ${filterFields} };`
+        `${pad}${objKey}: { method: ${safeMethod}; url: ${safeUrl}; params: ${params}; query: ${query}; body: ${body}; response: ${response}; error: ${error}; filterFields: ${filterFields}; stream: ${stream} };`
       );
     } else {
       lines.push(`${pad}${objKey}: {`);
@@ -800,15 +826,21 @@ function emitReqHelper() {
     ""
   ];
 }
-function renderLeaf(pad, objKey, req, requestExpr, members) {
+function renderLeaf(pad, objKey, req, requestExpr, members, streamExpr) {
   const lines = [`${pad}${objKey}: (input?: ${req.inputType}) => ({`];
   lines.push(`${pad}  ...__req<${req.responseType}>(() => ${requestExpr}),`);
+  if (streamExpr) {
+    lines.push(`${pad}  stream: () => ${streamExpr},`);
+  }
   for (const [name, value] of Object.entries(members)) {
     lines.push(`${pad}  ${name}: ${value},`);
   }
   lines.push(`${pad}}),`);
   return lines;
 }
+function renderStreamExpr(req) {
+  return `fetcher.sse<${req.responseType}>(${req.urlExpr}, ${req.optsExpr})`;
+}
 function emitApiObjectBlock(tree, indent, p) {
   const pad = " ".repeat(indent);
   const lines = [];
@@ -843,7 +875,8 @@ function emitApiObjectBlock(tree, indent, p) {
     }
     const members = {};
     for (const [name, { value }] of owned) members[name] = value;
-    lines.push(...renderLeaf(pad, objKey, req, leaf.requestExpr, members));
+    const streamExpr = node.contractSource.stream ? renderStreamExpr(req) : void 0;
+    lines.push(...renderLeaf(pad, objKey, req, leaf.requestExpr, members, streamExpr));
   }
   return lines;
 }
@@ -881,6 +914,8 @@ var ROUTE_NAMESPACE = [
   '  export type Params<K extends string> = ResolveByName<K, "params">;',
   '  export type Error<K extends string> = ResolveByName<K, "error">;',
   '  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">;',
   "  export type Request<K extends string> = {",
   "    body: Body<K>;",
   "    query: Query<K>;",
@@ -897,6 +932,7 @@ var PATH_NAMESPACE = [
   '  export type Params<M extends string, U extends string> = ResolveByPath<M, U, "params">;',
   '  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">;',
   "}",
   ""
 ];
@@ -908,6 +944,7 @@ var EMPTY_ROUTE_NAMESPACE = [
   "  export type Params<K extends string> = never;",
   "  export type Error<K extends string> = never;",
   "  export type FilterFields<K extends string> = never;",
+  "  export type Stream<K extends string> = never;",
   "  export type Request<K extends string> = { body: never; query: never; params: never };",
   "}",
   ""
@@ -920,6 +957,7 @@ var EMPTY_PATH_NAMESPACE = [
   "  export type Params<M extends string, U extends string> = never;",
   "  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;",
   "}",
   ""
 ];
@@ -943,7 +981,7 @@ function buildApiFile(routes, outDir, opts = {}) {
   for (const r of contracted) {
     const cs = r.contract?.contractSource;
     if (!cs) continue;
-    const refs = r.controllerRef ? [cs.queryRef, cs.bodyRef] : [cs.queryRef, cs.bodyRef, cs.responseRef];
+    const refs = r.controllerRef && !cs.stream ? [cs.queryRef, cs.bodyRef, cs.errorRef] : [cs.queryRef, cs.bodyRef, cs.responseRef, cs.errorRef];
     for (const ref of refs) {
       if (!ref) continue;
       let names = importsByFile.get(ref.filePath);
@@ -1376,11 +1414,470 @@ async function emitIndex(outDir, hasContracts = false, hasForms = false) {
   await writeFile4(join7(outDir, "index.d.ts"), content, "utf8");
 }
 
-// src/emit/emit-pages.ts
+// src/emit/emit-mocks.ts
 import { mkdir as mkdir5, writeFile as writeFile5 } from "fs/promises";
-import { join as join8, relative as relative5 } from "path";
-async function emitPages(pages, outDir, _options = {}) {
+import { join as join8 } from "path";
+
+// src/ir/schema-node-to-json-schema.ts
+var DEFAULT_CTX = { refPrefix: "#/components/schemas/" };
+function parseLiteral(raw) {
+  const t = raw.trim();
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (t === "null") return null;
+  const q = t[0];
+  if ((q === "'" || q === '"' || q === "`") && t[t.length - 1] === q) {
+    return t.slice(1, -1).replace(/\\'/g, "'").replace(/\\"/g, '"').replace(/\\`/g, "`").replace(/\\\\/g, "\\");
+  }
+  if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(t)) {
+    return Number(t);
+  }
+  return t;
+}
+function literalsType(values) {
+  const types = new Set(values.map((v) => v === null ? "null" : typeof v));
+  if (types.size === 1) {
+    const only = [...types][0];
+    if (only === "string") return "string";
+    if (only === "number") return "number";
+    if (only === "boolean") return "boolean";
+  }
+  return void 0;
+}
+function convert(node, ctx) {
+  switch (node.kind) {
+    case "string": {
+      const out = { type: "string" };
+      for (const c of node.checks) {
+        if (c.check === "email") out.format = "email";
+        else if (c.check === "url") out.format = "uri";
+        else if (c.check === "uuid") out.format = "uuid";
+        else if (c.check === "min") out.minLength = Number(c.value);
+        else if (c.check === "max") out.maxLength = Number(c.value);
+        else if (c.check === "regex") {
+          const m = /^\/(.*)\/[a-z]*$/.exec(c.pattern);
+          out.pattern = m ? m[1] : c.pattern;
+        }
+      }
+      return out;
+    }
+    case "number": {
+      const out = { type: "number" };
+      for (const c of node.checks) {
+        if (c.check === "int") out.type = "integer";
+        else if (c.check === "min") out.minimum = Number(c.value);
+        else if (c.check === "max") out.maximum = Number(c.value);
+        else if (c.check === "positive") out.exclusiveMinimum = 0;
+        else if (c.check === "negative") out.exclusiveMaximum = 0;
+      }
+      return out;
+    }
+    case "boolean":
+      return { type: "boolean" };
+    case "date":
+      return { type: "string", format: "date-time" };
+    case "unknown":
+      return node.note ? { description: node.note } : {};
+    case "instanceof":
+      return { type: "object", description: `instanceof ${node.ctor}` };
+    case "enum": {
+      const values = node.literals.map(parseLiteral);
+      const t = literalsType(values);
+      const out = { enum: values };
+      if (t) out.type = t;
+      return out;
+    }
+    case "literal": {
+      const value = parseLiteral(node.raw);
+      const out = { const: value };
+      const t = literalsType([value]);
+      if (t) out.type = t;
+      return out;
+    }
+    case "union": {
+      const options = node.options.map((o) => convert(o, ctx));
+      const out = { oneOf: options };
+      if (node.discriminator) {
+        out.discriminator = { propertyName: node.discriminator };
+      }
+      return out;
+    }
+    case "object": {
+      const properties = {};
+      const required = [];
+      for (const f of node.fields) {
+        if (f.value.kind === "optional") {
+          properties[f.key] = convert(f.value.inner, ctx);
+        } else {
+          properties[f.key] = convert(f.value, ctx);
+          required.push(f.key);
+        }
+      }
+      const out = { type: "object", properties };
+      if (required.length > 0) out.required = required;
+      out.additionalProperties = node.passthrough;
+      return out;
+    }
+    case "array":
+      return { type: "array", items: convert(node.element, ctx) };
+    case "optional":
+      return widenNullable(convert(node.inner, ctx));
+    case "ref":
+    case "lazyRef":
+      return { $ref: `${ctx.refPrefix}${node.name}` };
+    case "annotated":
+      return convert(node.inner, ctx);
+  }
+}
+function widenNullable(schema) {
+  if (schema.$ref) {
+    return { anyOf: [schema, { type: "null" }] };
+  }
+  if (typeof schema.type === "string") {
+    return { ...schema, type: [schema.type, "null"] };
+  }
+  if (Array.isArray(schema.type)) {
+    return schema.type.includes("null") ? schema : { ...schema, type: [...schema.type, "null"] };
+  }
+  return { anyOf: [schema, { type: "null" }] };
+}
+function schemaNodeToJsonSchema(node, ctx = DEFAULT_CTX) {
+  return convert(node, ctx);
+}
+function schemaModuleToJsonSchema(mod, ctx = DEFAULT_CTX) {
+  const named = {};
+  for (const [name, node] of mod.named) {
+    named[name] = convert(node, ctx);
+  }
+  return { root: convert(mod.root, ctx), named };
+}
+
+// src/emit/mock-gen-runtime.ts
+var MOCK_GEN_RUNTIME = `
+/** mulberry32 \u2014 a tiny, fast, seedable PRNG. \`next()\` returns a float in [0, 1). */
+function makeRng(seed) {
+  let a = seed >>> 0;
+  return {
+    next() {
+      a |= 0;
+      a = (a + 0x6d2b79f5) | 0;
+      let t = Math.imul(a ^ (a >>> 15), 1 | a);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    },
+  };
+}
+
+function __pick(rng, items) {
+  return items[Math.floor(rng.next() * items.length)];
+}
+
+function __intBetween(rng, min, max) {
+  return Math.floor(rng.next() * (max - min + 1)) + min;
+}
+
+const __WORDS = ['lorem', 'ipsum', 'dolor', 'sit', 'amet', 'consectetur', 'adipiscing', 'elit', 'sed', 'tempor'];
+const __FIRST_NAMES = ['Ada', 'Alan', 'Grace', 'Linus', 'Margaret', 'Dennis'];
+const __LAST_NAMES = ['Lovelace', 'Turing', 'Hopper', 'Torvalds', 'Hamilton', 'Ritchie'];
+
+function __fakeWords(rng, count) {
+  let out = [];
+  for (let i = 0; i < count; i++) out.push(__pick(rng, __WORDS));
+  return out.join(' ');
+}
+
+function __hex(rng, len) {
+  let s = '';
+  for (let i = 0; i < len; i++) s += Math.floor(rng.next() * 16).toString(16);
+  return s;
+}
+
+function __fakeUuid(rng) {
+  return __hex(rng, 8) + '-' + __hex(rng, 4) + '-4' + __hex(rng, 3) + '-' + __pick(rng, ['8', '9', 'a', 'b']) + __hex(rng, 3) + '-' + __hex(rng, 12);
+}
+
+function __fakeString(rng, schema) {
+  switch (schema.format) {
+    case 'email':
+      return __pick(rng, __FIRST_NAMES).toLowerCase() + '.' + __pick(rng, __LAST_NAMES).toLowerCase() + '@example.com';
+    case 'uri':
+    case 'url':
+      return 'https://example.com/' + __pick(rng, __WORDS);
+    case 'uuid':
+      return __fakeUuid(rng);
+    case 'date-time':
+      return new Date(Date.UTC(2020, __intBetween(rng, 0, 11), __intBetween(rng, 1, 28))).toISOString();
+    default:
+      return __fakeWords(rng, __intBetween(rng, 1, 3));
+  }
+}
+
+/** Generate a mock value for a JSON Schema node (depth-capped recursion via $ref). */
+function generateMock(schema, rng, defs, depth) {
+  defs = defs || {};
+  depth = depth || 0;
+  if (schema.$ref) {
+    const name = schema.$ref.replace('#/components/schemas/', '');
+    const target = defs[name];
+    if (!target || depth > 4) return null;
+    return generateMock(target, rng, defs, depth + 1);
+  }
+  if ('const' in schema) return schema.const;
+  if (schema.enum && schema.enum.length > 0) return __pick(rng, schema.enum);
+  if (schema.oneOf && schema.oneOf.length > 0) return generateMock(__pick(rng, schema.oneOf), rng, defs, depth);
+  if (schema.anyOf && schema.anyOf.length > 0) return generateMock(__pick(rng, schema.anyOf), rng, defs, depth);
+  let type = Array.isArray(schema.type)
+    ? (schema.type.filter((t) => t !== 'null')[0] || 'null')
+    : schema.type;
+  switch (type) {
+    case 'string':
+      return __fakeString(rng, schema);
+    case 'integer':
+      return __intBetween(rng, typeof schema.minimum === 'number' ? schema.minimum : 0, typeof schema.maximum === 'number' ? schema.maximum : 1000);
+    case 'number':
+      return __intBetween(rng, typeof schema.minimum === 'number' ? schema.minimum : 0, typeof schema.maximum === 'number' ? schema.maximum : 1000) + Math.round(rng.next() * 100) / 100;
+    case 'boolean':
+      return rng.next() < 0.5;
+    case 'null':
+      return null;
+    case 'array': {
+      const count = depth > 2 ? 0 : __intBetween(rng, 1, 2);
+      const items = schema.items || {};
+      let arr = [];
+      for (let i = 0; i < count; i++) arr.push(generateMock(items, rng, defs, depth + 1));
+      return arr;
+    }
+    case 'object': {
+      const out = {};
+      const props = schema.properties || {};
+      for (const key of Object.keys(props)) out[key] = generateMock(props[key], rng, defs, depth + 1);
+      return out;
+    }
+    default:
+      return {};
+  }
+}
+`.trim();
+
+// src/emit/emit-mocks.ts
+var REF_PREFIX = "#/components/schemas/";
+function toMswPath(path, baseUrl) {
+  return `${baseUrl}${path}`;
+}
+function responseSchemaFor(route, defs) {
+  const cs = route.contract.contractSource;
+  if (cs.responseSchema) {
+    const { root, named } = schemaModuleToJsonSchema(cs.responseSchema, { refPrefix: REF_PREFIX });
+    for (const [name, node] of Object.entries(named)) {
+      if (!(name in defs)) defs[name] = node;
+    }
+    return root;
+  }
+  return {};
+}
+function buildMocksFile(routes, opts = {}) {
+  const seed = opts.seed ?? 1;
+  const baseUrl = opts.baseUrl ?? "";
+  const contracted = routes.filter((r) => r.contract);
+  const defs = {};
+  const handlers = [];
+  for (const r of contracted) {
+    const schema = responseSchemaFor(r, defs);
+    const method = r.method.toLowerCase();
+    const mswMethod = method === "get" || method === "post" || method === "put" || method === "patch" || method === "delete" ? method : "all";
+    const path = toMswPath(r.path, baseUrl);
+    const cs = r.contract.contractSource;
+    const schemaLiteral = JSON.stringify(schema);
+    const pathLit = JSON.stringify(path);
+    if (cs.stream) {
+      handlers.push(
+        [
+          `  // ${r.name} (stream)`,
+          `  http.${mswMethod}(${pathLit}, () => {`,
+          `    const value = generateMock(${schemaLiteral}, makeRng(SEED), DEFS);`,
+          "    const body = `data: ${JSON.stringify(value)}\\n\\n`;",
+          "    return new HttpResponse(body, { headers: { 'Content-Type': 'text/event-stream' } });",
+          "  }),"
+        ].join("\n")
+      );
+    } else {
+      handlers.push(
+        [
+          `  // ${r.name}`,
+          `  http.${mswMethod}(${pathLit}, () => {`,
+          `    const value = generateMock(${schemaLiteral}, makeRng(SEED), DEFS);`,
+          "    return HttpResponse.json(value);",
+          "  }),"
+        ].join("\n")
+      );
+    }
+  }
+  const lines = [
+    "// Generated by @dudousxd/nestjs-codegen. Do not edit.",
+    "// MSW handlers returning deterministic, schema-shaped mock data.",
+    "/* eslint-disable */",
+    "// @ts-nocheck",
+    "",
+    "import { http, HttpResponse } from 'msw';",
+    "",
+    `const SEED = ${seed};`,
+    "",
+    "// ---------------------------------------------------------------------------",
+    "// Embedded mock-data runtime (mulberry32 PRNG + JSON-Schema value generator).",
+    "// Dependency-free: no @faker-js/faker. Deterministic for a given SEED.",
+    "// ---------------------------------------------------------------------------",
+    MOCK_GEN_RUNTIME,
+    "",
+    "// Shared component schemas referenced by $ref.",
+    `const DEFS = ${JSON.stringify(defs, null, 2)};`,
+    "",
+    "/** MSW request handlers, one per contracted route. */",
+    "export const handlers = [",
+    ...handlers,
+    "];",
+    ""
+  ];
+  return lines.join("\n");
+}
+async function emitMocks(routes, outDir, opts = {}) {
   await mkdir5(outDir, { recursive: true });
+  const content = buildMocksFile(routes, opts);
+  const fileName = opts.fileName ?? "mocks.ts";
+  await writeFile5(join8(outDir, fileName), content, "utf8");
+}
+
+// src/emit/emit-openapi.ts
+import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
+import { join as join9 } from "path";
+var REF_PREFIX2 = "#/components/schemas/";
+function toOpenApiPath(path) {
+  return path.replace(/:([^/]+)/g, "{$1}");
+}
+function positionSchema(schema, tsType, components) {
+  if (schema) {
+    const { root, named } = schemaModuleToJsonSchema(schema, { refPrefix: REF_PREFIX2 });
+    for (const [name, node] of Object.entries(named)) {
+      if (!(name in components)) components[name] = node;
+    }
+    return root;
+  }
+  return tsType ? { description: tsType } : {};
+}
+function buildParameters(route) {
+  const params = [];
+  for (const p of route.params) {
+    if (p.source === "path") {
+      params.push({
+        name: p.name,
+        in: "path",
+        required: true,
+        schema: { type: "string" }
+      });
+    } else if (p.source === "query") {
+      params.push({
+        name: p.name,
+        in: "query",
+        required: false,
+        schema: { type: "string" }
+      });
+    } else if (p.source === "header") {
+      params.push({
+        name: p.name,
+        in: "header",
+        required: false,
+        schema: { type: "string" }
+      });
+    }
+  }
+  return params;
+}
+function buildResponses(cs, components) {
+  const responses = {};
+  const successSchema = positionSchema(
+    // Prefer rich response IR when present; otherwise fall back to the TS type.
+    cs.responseSchema ?? null,
+    cs.response,
+    components
+  );
+  const successContentType = cs.stream ? "text/event-stream" : "application/json";
+  responses["200"] = {
+    description: cs.stream ? "Server-sent event stream" : "Successful response",
+    content: { [successContentType]: { schema: successSchema } }
+  };
+  const errorSchema = positionSchema(null, cs.error ?? null, components);
+  const errorBody = {
+    description: "Error response",
+    content: { "application/json": { schema: errorSchema } }
+  };
+  if (cs.error || cs.errorRef) {
+    responses["400"] = errorBody;
+    responses.default = errorBody;
+  } else {
+    responses.default = {
+      description: "Error response",
+      content: { "application/json": { schema: {} } }
+    };
+  }
+  return responses;
+}
+function buildOperation(route, components) {
+  const cs = route.contract.contractSource;
+  const op = {
+    operationId: route.name,
+    parameters: buildParameters(route),
+    responses: buildResponses(cs, components)
+  };
+  const method = route.method.toUpperCase();
+  const hasBody = method !== "GET" && method !== "HEAD" && method !== "DELETE";
+  if (hasBody && (cs.bodySchema || cs.body)) {
+    const bodySchema = positionSchema(cs.bodySchema, cs.body, components);
+    op.requestBody = {
+      required: true,
+      content: { "application/json": { schema: bodySchema } }
+    };
+  }
+  return op;
+}
+function buildOpenApiSpec(routes, opts = {}) {
+  const components = {};
+  const paths = {};
+  for (const route of routes) {
+    if (!route.contract) continue;
+    const oaPath = toOpenApiPath(route.path);
+    const method = route.method.toLowerCase();
+    let pathItem = paths[oaPath];
+    if (!pathItem) {
+      pathItem = {};
+      paths[oaPath] = pathItem;
+    }
+    pathItem[method] = buildOperation(route, components);
+  }
+  const info = opts.info ?? {};
+  const doc = {
+    openapi: "3.1.0",
+    info: {
+      title: info.title ?? "NestJS API",
+      version: info.version ?? "1.0.0",
+      ...info.description ? { description: info.description } : {}
+    },
+    paths,
+    components: { schemas: components }
+  };
+  return doc;
+}
+async function emitOpenApi(routes, outDir, opts = {}) {
+  await mkdir6(outDir, { recursive: true });
+  const doc = buildOpenApiSpec(routes, opts);
+  const fileName = opts.fileName ?? "openapi.json";
+  await writeFile6(join9(outDir, fileName), `${JSON.stringify(doc, null, 2)}
+`, "utf8");
+}
+
+// src/emit/emit-pages.ts
+import { mkdir as mkdir7, writeFile as writeFile7 } from "fs/promises";
+import { join as join10, relative as relative5 } from "path";
+async function emitPages(pages, outDir, _options = {}) {
+  await mkdir7(outDir, { recursive: true });
   const pageNameUnion = pages.length > 0 ? pages.map((p) => JSON.stringify(p.name)).join(" | ") : "never";
   const augBody = pages.map((p) => {
     const key = needsQuotes(p.name) ? JSON.stringify(p.name) : p.name;
@@ -1399,7 +1896,7 @@ ${augBody}
   }
 ${sharedPropsBlock}}
 `;
-  await writeFile5(join8(outDir, "pages.d.ts"), content, "utf8");
+  await writeFile7(join10(outDir, "pages.d.ts"), content, "utf8");
 }
 function buildSharedPropsBlock(sharedProps) {
   if (!sharedProps) return "";
@@ -1429,12 +1926,12 @@ function needsQuotes(name) {
 }
 
 // src/emit/emit-routes.ts
-import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
-import { join as join9 } from "path";
+import { mkdir as mkdir8, writeFile as writeFile8 } from "fs/promises";
+import { join as join11 } from "path";
 async function emitRoutes(routes, outDir) {
-  await mkdir6(outDir, { recursive: true });
+  await mkdir8(outDir, { recursive: true });
   const content = buildRoutesFile(routes);
-  await writeFile6(join9(outDir, "routes.ts"), content, "utf8");
+  await writeFile8(join11(outDir, "routes.ts"), content, "utf8");
 }
 function buildRoutesFile(routes) {
   if (routes.length === 0) {
@@ -1582,24 +2079,41 @@ async function generate(config, inputRoutes = []) {
     });
   }
   const hasForms = await emitForms(routes, config.codegen.outDir, config.forms, config.validation);
+  if (hasContracts && config.openapi.enabled) {
+    await emitOpenApi(routes, config.codegen.outDir, {
+      fileName: config.openapi.fileName,
+      info: {
+        title: config.openapi.title,
+        version: config.openapi.version,
+        ...config.openapi.description ? { description: config.openapi.description } : {}
+      }
+    });
+  }
+  if (hasContracts && config.mocks.enabled) {
+    await emitMocks(routes, config.codegen.outDir, {
+      fileName: config.mocks.fileName,
+      seed: config.mocks.seed,
+      baseUrl: config.mocks.baseUrl
+    });
+  }
   await emitIndex(config.codegen.outDir, hasContracts, hasForms);
   if (extensions.length > 0) {
     const extraFiles = await collectEmittedFiles(extensions, ctx);
     for (const file of extraFiles) {
-      const dest = join10(config.codegen.outDir, file.path);
-      await mkdir7(dirname2(dest), { recursive: true });
-      await writeFile7(dest, file.contents, "utf8");
+      const dest = join12(config.codegen.outDir, file.path);
+      await mkdir9(dirname2(dest), { recursive: true });
+      await writeFile9(dest, file.contents, "utf8");
     }
   }
 }
 
 // src/watch/watcher.ts
 import { readFile as readFile3 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join15 } from "path";
 import chokidar from "chokidar";
 
 // src/discovery/contracts-fast.ts
-import { join as join11, resolve as resolve3 } from "path";
+import { join as join13, resolve as resolve3 } from "path";
 import fg2 from "fast-glob";
 import {
   Node as Node8,
@@ -1781,10 +2295,85 @@ function followModuleForType(name, moduleSpecifier, fromFile, project, seen) {
   }
   return null;
 }
+function resolveImportedVariable(name, sourceFile, project) {
+  const local = sourceFile.getVariableDeclaration(name);
+  if (local) return { decl: local, file: sourceFile };
+  return resolveVariableViaImports(name, sourceFile, project, /* @__PURE__ */ new Set());
+}
+function resolveVariableViaImports(name, sourceFile, project, seen) {
+  for (const importDecl of sourceFile.getImportDeclarations()) {
+    const namedImport = importDecl.getNamedImports().find((n) => (n.getAliasNode()?.getText() ?? n.getName()) === name);
+    if (!namedImport) continue;
+    const sourceName = namedImport.getName();
+    const moduleSpecifier = importDecl.getModuleSpecifierValue();
+    const found = followModuleForVariable(sourceName, moduleSpecifier, sourceFile, project, seen);
+    if (found) return found;
+  }
+  return null;
+}
+function followModuleForVariable(name, moduleSpecifier, fromFile, project, seen) {
+  const candidates = resolveModuleSpecifier(moduleSpecifier, fromFile, project);
+  for (const candidate of candidates) {
+    let importedFile = project.getSourceFile(candidate);
+    if (!importedFile) {
+      try {
+        importedFile = project.addSourceFileAtPath(candidate);
+      } catch {
+        continue;
+      }
+    }
+    const found = resolveVariableInFile(name, importedFile, project, seen);
+    if (found) return found;
+  }
+  return null;
+}
+function resolveVariableInFile(name, file, project, seen) {
+  const filePath = file.getFilePath();
+  if (seen.has(filePath)) return null;
+  seen.add(filePath);
+  const local = file.getVariableDeclaration(name);
+  if (local) return { decl: local, file };
+  for (const exportDecl of file.getExportDeclarations()) {
+    const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+    const namedExports = exportDecl.getNamedExports();
+    if (moduleSpecifier) {
+      const hasStar = namedExports.length === 0;
+      const reExport2 = namedExports.find(
+        (n) => (n.getAliasNode()?.getText() ?? n.getName()) === name
+      );
+      if (!hasStar && !reExport2) continue;
+      const sourceName2 = hasStar ? name : reExport2?.getName() ?? name;
+      const found = followModuleForVariable(sourceName2, moduleSpecifier, file, project, seen);
+      if (found) return found;
+      continue;
+    }
+    const reExport = namedExports.find(
+      (n) => (n.getAliasNode()?.getText() ?? n.getName()) === name
+    );
+    if (!reExport) continue;
+    const sourceName = reExport.getName();
+    const viaImports = resolveVariableViaImports(sourceName, file, project, seen);
+    if (viaImports) return viaImports;
+  }
+  return null;
+}
+var _findTypeCache = /* @__PURE__ */ new WeakMap();
+function clearTypeResolutionCaches(project) {
+  _findTypeCache.delete(project);
+  _resolveNamedRefCache.delete(project);
+}
 function findType(name, sourceFile, project) {
+  let byKey = _findTypeCache.get(project);
+  if (byKey === void 0) {
+    byKey = /* @__PURE__ */ new Map();
+    _findTypeCache.set(project, byKey);
+  }
+  const key = `${sourceFile.getFilePath()}\0${name}`;
+  if (byKey.has(key)) return byKey.get(key) ?? null;
   const local = findTypeInFile(name, sourceFile);
-  if (local) return local;
-  return resolveImportedType(name, sourceFile, project);
+  const result = local ?? resolveImportedType(name, sourceFile, project);
+  byKey.set(key, result);
+  return result;
 }
 var _NON_REF_NAMES = /* @__PURE__ */ new Set(["string", "number", "boolean", "void", "unknown", "any", "Date"]);
 function _localDeclForKinds(name, file, kinds) {
@@ -1821,6 +2410,26 @@ function resolveTypeRef(nodeOrName, sourceFile, project, opts) {
     if (_NON_REF_NAMES.has(refName)) return null;
     name = refName;
   }
+  return _resolveNamedRef(name, sourceFile, project, opts);
+}
+var _resolveNamedRefCache = /* @__PURE__ */ new WeakMap();
+function _resolveNamedRef(name, sourceFile, project, opts) {
+  let byKey = _resolveNamedRefCache.get(project);
+  if (byKey === void 0) {
+    byKey = /* @__PURE__ */ new Map();
+    _resolveNamedRefCache.set(project, byKey);
+  }
+  const kindsKey = [...opts.kinds].sort().join(",");
+  const key = `${sourceFile.getFilePath()}\0${name}\0${kindsKey}\0${opts.allowBareSpecifier ? 1 : 0}`;
+  if (byKey.has(key)) {
+    const cached = byKey.get(key) ?? null;
+    return cached ? { ...cached } : null;
+  }
+  const computed = _computeNamedRef(name, sourceFile, project, opts);
+  byKey.set(key, computed);
+  return computed ? { ...computed } : null;
+}
+function _computeNamedRef(name, sourceFile, project, opts) {
   if (_localDeclForKinds(name, sourceFile, opts.kinds)) {
     return { name, filePath: sourceFile.getFilePath() };
   }
@@ -1895,7 +2504,8 @@ function extractSchemaFromDto(classDecl, sourceFile, project) {
     emittedClasses: /* @__PURE__ */ new Map(),
     visiting: /* @__PURE__ */ new Set(),
     recursiveSchemas: /* @__PURE__ */ new Set(),
-    depth: 0
+    depth: 0,
+    typeBindings: /* @__PURE__ */ new Map()
   };
   const root = buildObject(classDecl, sourceFile, ctx);
   return { root, named: ctx.named, warnings: ctx.warnings, recursive: ctx.recursiveSchemas };
@@ -1919,11 +2529,34 @@ function buildProperty(prop, classFile, ctx) {
   const typeNode = prop.getTypeNode();
   const typeText = typeNode?.getText() ?? "unknown";
   const isArrayType = !!typeNode && Node3.isArrayTypeNode(typeNode);
+  const discriminator = resolveDiscriminator(dec("Type"));
+  if (discriminator) {
+    const options = discriminator.subTypes.map(
+      (name) => buildNestedReference(name, classFile, ctx)
+    );
+    const unionNode = {
+      kind: "union",
+      options,
+      discriminator: discriminator.property
+    };
+    const wrapArray = has("IsArray") || isArrayType;
+    const node2 = wrapArray ? { kind: "array", element: unionNode } : unionNode;
+    return applyPresence(node2, decorators);
+  }
+  const propTypeParam = singularClassName(typeText);
+  if (propTypeParam && ctx.typeBindings.has(propTypeParam)) {
+    const bound = ctx.typeBindings.get(propTypeParam);
+    const childNode = buildNestedReference(bound, classFile, ctx);
+    const wrapArray = has("IsArray") || isArrayType;
+    const node2 = wrapArray ? { kind: "array", element: childNode } : childNode;
+    return applyPresence(node2, decorators);
+  }
   const typeRefName = resolveTypeFactoryName(dec("Type"));
   if (has("ValidateNested") || typeRefName) {
+    const typeArgs = genericTypeArgNames(typeNode);
     const childName = typeRefName ?? singularClassName(typeText);
     if (childName) {
-      const childNode = buildNestedReference(childName, classFile, ctx);
+      const childNode = buildNestedReference(childName, classFile, ctx, typeArgs);
       const wrapArray = has("IsArray") || isArrayType;
       const node2 = wrapArray ? { kind: "array", element: childNode } : childNode;
       return applyPresence(node2, decorators);
@@ -2048,10 +2681,12 @@ function baseFromType(typeText, isArrayType) {
       return { kind: "unknown" };
   }
 }
-function buildNestedReference(className, fromFile, ctx) {
-  if (ctx.visiting.has(className)) {
-    const reserved = ctx.emittedClasses.get(className) ?? aliasFor(className, ctx);
-    ctx.emittedClasses.set(className, reserved);
+function buildNestedReference(className, fromFile, ctx, typeArgs = []) {
+  const cacheKey = typeArgs.length > 0 ? `${className}<${typeArgs.join(",")}>` : className;
+  const schemaBase = typeArgs.length > 0 ? `${className}Of${typeArgs.join("")}` : className;
+  if (ctx.visiting.has(cacheKey)) {
+    const reserved = ctx.emittedClasses.get(cacheKey) ?? aliasFor(schemaBase, ctx);
+    ctx.emittedClasses.set(cacheKey, reserved);
     ctx.recursiveSchemas.add(reserved);
     if (!ctx.warnedDecorators.has(`recursive:${reserved}`)) {
       ctx.warnedDecorators.add(`recursive:${reserved}`);
@@ -2070,19 +2705,27 @@ function buildNestedReference(className, fromFile, ctx) {
     }
     return { kind: "unknown", note: "nesting too deep \u2014 not expanded" };
   }
-  const existing = ctx.emittedClasses.get(className);
+  const existing = ctx.emittedClasses.get(cacheKey);
   if (existing) return { kind: "ref", name: existing };
-  const schemaName = aliasFor(className, ctx);
+  const schemaName = aliasFor(schemaBase, ctx);
   const resolved = findType(className, fromFile, ctx.project);
   if (!resolved || resolved.kind !== "class") {
     return { kind: "object", fields: [], passthrough: true };
   }
-  ctx.emittedClasses.set(className, schemaName);
-  ctx.visiting.add(className);
+  const params = resolved.decl.getTypeParameters().map((p) => p.getName());
+  const newBindings = [];
+  params.forEach((param, i) => {
+    const arg = typeArgs[i];
+    if (arg) newBindings.push([param, arg]);
+  });
+  for (const [k, v] of newBindings) ctx.typeBindings.set(k, v);
+  ctx.emittedClasses.set(cacheKey, schemaName);
+  ctx.visiting.add(cacheKey);
   ctx.depth += 1;
   const childNode = buildObject(resolved.decl, resolved.file, ctx);
   ctx.depth -= 1;
-  ctx.visiting.delete(className);
+  ctx.visiting.delete(cacheKey);
+  for (const [k] of newBindings) ctx.typeBindings.delete(k);
   ctx.named.set(schemaName, childNode);
   return { kind: "ref", name: schemaName };
 }
@@ -2129,6 +2772,39 @@ function messageRaw(decorator) {
   }
   return void 0;
 }
+function resolveDiscriminator(decorator) {
+  const optsArg = decorator?.getArguments()[1];
+  if (!optsArg || !Node3.isObjectLiteralExpression(optsArg)) return null;
+  let discProp;
+  for (const prop of optsArg.getProperties()) {
+    if (Node3.isPropertyAssignment(prop) && prop.getName() === "discriminator") {
+      discProp = prop.getInitializer();
+    }
+  }
+  if (!discProp || !Node3.isObjectLiteralExpression(discProp)) return null;
+  let property = null;
+  const subTypes = [];
+  for (const prop of discProp.getProperties()) {
+    if (!Node3.isPropertyAssignment(prop)) continue;
+    const name = prop.getName();
+    const init = prop.getInitializer();
+    if (!init) continue;
+    if (name === "property" && Node3.isStringLiteral(init)) {
+      property = init.getLiteralValue();
+    } else if (name === "subTypes" && Node3.isArrayLiteralExpression(init)) {
+      for (const el of init.getElements()) {
+        if (!Node3.isObjectLiteralExpression(el)) continue;
+        for (const p of el.getProperties()) {
+          if (!Node3.isPropertyAssignment(p) || p.getName() !== "name") continue;
+          const nameInit = p.getInitializer();
+          if (nameInit && Node3.isIdentifier(nameInit)) subTypes.push(nameInit.getText());
+        }
+      }
+    }
+  }
+  if (!property || subTypes.length === 0) return null;
+  return { property, subTypes };
+}
 function resolveTypeFactoryName(decorator) {
   const arg = firstArg(decorator);
   if (!arg) return null;
@@ -2142,6 +2818,17 @@ function singularClassName(typeText) {
   const inner = typeText.endsWith("[]") ? typeText.slice(0, -2).trim() : typeText;
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(inner) ? inner : null;
 }
+function genericTypeArgNames(typeNode) {
+  if (!typeNode || !Node3.isTypeReference(typeNode)) return [];
+  const names = [];
+  for (const arg of typeNode.getTypeArguments()) {
+    if (!Node3.isTypeReference(arg)) return [];
+    const tn = arg.getTypeName();
+    if (!Node3.isIdentifier(tn)) return [];
+    names.push(tn.getText());
+  }
+  return names;
+}
 function enumSchemaFromDecorator(decorator, classFile, ctx) {
   const arg = firstArg(decorator);
   if (!arg) return null;
@@ -2200,17 +2887,34 @@ import {
 } from "ts-morph";
 
 // src/discovery/enum-resolution.ts
+var _enumCache = /* @__PURE__ */ new WeakMap();
+function clearEnumCache(project) {
+  _enumCache.delete(project);
+}
 function resolveEnumValues(name, sourceFile, project) {
+  let byKey = _enumCache.get(project);
+  if (byKey === void 0) {
+    byKey = /* @__PURE__ */ new Map();
+    _enumCache.set(project, byKey);
+  }
+  const key = `${sourceFile.getFilePath()}\0${name}`;
+  if (byKey.has(key)) {
+    const cached = byKey.get(key) ?? null;
+    return cached ? { values: [...cached.values], numeric: cached.numeric } : null;
+  }
   const resolved = findType(name, sourceFile, project);
-  if (!resolved || resolved.kind !== "enum") return null;
-  let numeric = true;
-  const values = resolved.members.map((m) => {
-    const parsed = JSON.parse(m);
-    if (typeof parsed === "string") numeric = false;
-    return String(parsed);
-  });
-  if (values.length === 0) return null;
-  return { values, numeric };
+  let result = null;
+  if (resolved && resolved.kind === "enum") {
+    let numeric = true;
+    const values = resolved.members.map((m) => {
+      const parsed = JSON.parse(m);
+      if (typeof parsed === "string") numeric = false;
+      return String(parsed);
+    });
+    if (values.length > 0) result = { values, numeric };
+  }
+  byKey.set(key, result);
+  return result ? { values: [...result.values], numeric: result.numeric } : null;
 }
 
 // src/discovery/filter-field-types.ts
@@ -2655,24 +3359,26 @@ var PASSTHROUGH_UTILITY = /* @__PURE__ */ new Set([
   "Map",
   "Set"
 ]);
-function resolveTypeNodeToString(typeNode, sourceFile, project, depth) {
+function resolveTypeNodeToString(typeNode, sourceFile, project, depth, subst = /* @__PURE__ */ new Map()) {
   if (depth <= 0) return "unknown";
   if (Node6.isArrayTypeNode(typeNode)) {
     const elementType = typeNode.getElementTypeNode();
-    return `Array<${resolveTypeNodeToString(elementType, sourceFile, project, depth)}>`;
+    return `Array<${resolveTypeNodeToString(elementType, sourceFile, project, depth, subst)}>`;
   }
   if (Node6.isUnionTypeNode(typeNode)) {
-    return typeNode.getTypeNodes().map((t) => resolveTypeNodeToString(t, sourceFile, project, depth)).join(" | ");
+    return typeNode.getTypeNodes().map((t) => resolveTypeNodeToString(t, sourceFile, project, depth, subst)).join(" | ");
   }
   if (Node6.isIntersectionTypeNode(typeNode)) {
-    return typeNode.getTypeNodes().map((t) => resolveTypeNodeToString(t, sourceFile, project, depth)).join(" & ");
+    return typeNode.getTypeNodes().map((t) => resolveTypeNodeToString(t, sourceFile, project, depth, subst)).join(" & ");
   }
   if (Node6.isParenthesizedTypeNode(typeNode)) {
-    return `(${resolveTypeNodeToString(typeNode.getTypeNode(), sourceFile, project, depth)})`;
+    return `(${resolveTypeNodeToString(typeNode.getTypeNode(), sourceFile, project, depth, subst)})`;
   }
   if (Node6.isTypeReference(typeNode)) {
     const typeName = typeNode.getTypeName();
     const name = Node6.isIdentifier(typeName) ? typeName.getText() : typeNode.getText();
+    const bound = subst.get(name);
+    if (bound !== void 0) return bound;
     if (name === "string" || name === "number" || name === "boolean") return name;
     if (name === "Date") return "string";
     if (name === "unknown" || name === "any" || name === "void") return "unknown";
@@ -2680,14 +3386,15 @@ function resolveTypeNodeToString(typeNode, sourceFile, project, depth) {
       return "unknown";
     const wrapperMode = WRAPPER_TYPES[name];
     if (wrapperMode) {
-      return unwrapFirstTypeArg(typeNode, sourceFile, project, depth, wrapperMode);
+      return unwrapFirstTypeArg(typeNode, sourceFile, project, depth, wrapperMode, subst);
     }
     if (PASSTHROUGH_UTILITY.has(name)) {
       return typeNode.getText();
     }
     const resolved = findType(name, sourceFile, project);
     if (resolved) {
-      return expandTypeDecl(resolved, project, depth - 1);
+      const childSubst = buildSubst(resolved, typeNode, sourceFile, project, depth, subst);
+      return expandTypeDecl(resolved, project, depth - 1, childSubst);
     }
     dbg("unresolvable type:", name, "in", sourceFile.getFilePath());
     return "unknown";
@@ -2700,32 +3407,45 @@ function resolveTypeNodeToString(typeNode, sourceFile, project, depth) {
   if (kind === SyntaxKind3.AnyKeyword) return "unknown";
   return typeNode.getText();
 }
-function unwrapFirstTypeArg(typeNode, sourceFile, project, depth, mode) {
+function unwrapFirstTypeArg(typeNode, sourceFile, project, depth, mode, subst = /* @__PURE__ */ new Map()) {
   const typeArgs = typeNode.getTypeArguments();
   const firstTypeArg = typeArgs[0];
   if (typeArgs.length > 0 && firstTypeArg !== void 0) {
-    const inner = resolveTypeNodeToString(firstTypeArg, sourceFile, project, depth);
+    const inner = resolveTypeNodeToString(firstTypeArg, sourceFile, project, depth, subst);
     return mode === "arrayOf" ? `Array<${inner}>` : inner;
   }
   return mode === "arrayOf" ? "Array<unknown>" : "unknown";
 }
-function expandTypeDecl(result, project, depth) {
+function buildSubst(result, typeNode, sourceFile, project, depth, parentSubst) {
+  if (result.kind !== "class" && result.kind !== "interface") return /* @__PURE__ */ new Map();
+  const params = result.decl.getTypeParameters().map((p) => p.getName());
+  if (params.length === 0) return /* @__PURE__ */ new Map();
+  const args = typeNode.getTypeArguments();
+  const subst = /* @__PURE__ */ new Map();
+  params.forEach((param, i) => {
+    const arg = args[i];
+    if (arg)
+      subst.set(param, resolveTypeNodeToString(arg, sourceFile, project, depth, parentSubst));
+  });
+  return subst;
+}
+function expandTypeDecl(result, project, depth, subst = /* @__PURE__ */ new Map()) {
   if (depth < 0) return "unknown";
   switch (result.kind) {
     case "class":
-      return resolvePropertied(result.decl, result.file, project, depth);
+      return resolvePropertied(result.decl, result.file, project, depth, subst);
     case "interface":
-      return resolvePropertied(result.decl, result.file, project, depth);
+      return resolvePropertied(result.decl, result.file, project, depth, subst);
     case "typeAlias":
       if (result.typeNode) {
-        return resolveTypeNodeToString(result.typeNode, result.file, project, depth);
+        return resolveTypeNodeToString(result.typeNode, result.file, project, depth, subst);
       }
       return result.text;
     case "enum":
       return result.members.join(" | ");
   }
 }
-function resolvePropertied(decl, sourceFile, project, depth) {
+function resolvePropertied(decl, sourceFile, project, depth, subst = /* @__PURE__ */ new Map()) {
   if (depth < 0) return "unknown";
   const lines = [];
   for (const prop of decl.getProperties()) {
@@ -2734,7 +3454,7 @@ function resolvePropertied(decl, sourceFile, project, depth) {
     const propTypeNode = prop.getTypeNode();
     let propType = "unknown";
     if (propTypeNode) {
-      propType = resolveTypeNodeToString(propTypeNode, sourceFile, project, depth);
+      propType = resolveTypeNodeToString(propTypeNode, sourceFile, project, depth, subst);
     }
     lines.push(`${propName}${isOptional ? "?" : ""}: ${propType}`);
   }
@@ -2783,7 +3503,7 @@ function extractParamsType(method, sourceFile, project) {
   return entries.length > 0 ? `{ ${entries.join("; ")} }` : null;
 }
 function extractResponseType(method, sourceFile, project) {
-  const apiResponseDecorator = method.getDecorator("ApiResponse");
+  const apiResponseDecorator = method.getDecorators().find((d) => d.getName() === "ApiResponse" && (apiResponseStatus(d) ?? 0) < 400);
   if (apiResponseDecorator) {
     const args = apiResponseDecorator.getArguments();
     const optsArg = args[0];
@@ -2812,6 +3532,59 @@ function extractResponseType(method, sourceFile, project) {
   }
   return "unknown";
 }
+function apiResponseStatus(decorator) {
+  const optsArg = decorator.getArguments()[0];
+  if (!optsArg || !Node6.isObjectLiteralExpression(optsArg)) return null;
+  for (const prop of optsArg.getProperties()) {
+    if (!Node6.isPropertyAssignment(prop)) continue;
+    if (prop.getName() !== "status") continue;
+    const val = prop.getInitializer();
+    if (val && Node6.isNumericLiteral(val)) return Number(val.getLiteralValue());
+  }
+  return null;
+}
+function apiResponseTypeNode(decorator) {
+  const optsArg = decorator.getArguments()[0];
+  if (!optsArg || !Node6.isObjectLiteralExpression(optsArg)) return null;
+  for (const prop of optsArg.getProperties()) {
+    if (!Node6.isPropertyAssignment(prop)) continue;
+    if (prop.getName() !== "type") continue;
+    const val = prop.getInitializer();
+    if (!val) return null;
+    if (Node6.isArrayLiteralExpression(val)) {
+      const first = val.getElements()[0];
+      return first ? { node: first, isArray: true } : null;
+    }
+    return { node: val, isArray: false };
+  }
+  return null;
+}
+function extractErrorType(method, sourceFile, project) {
+  for (const decorator of method.getDecorators()) {
+    if (decorator.getName() !== "ApiResponse") continue;
+    const status = apiResponseStatus(decorator);
+    if (status === null || status < 400) continue;
+    const typeInfo = apiResponseTypeNode(decorator);
+    if (!typeInfo) continue;
+    const inner = resolveIdentifierToClassType(typeInfo.node, sourceFile, project, 3);
+    const type = typeInfo.isArray ? `Array<${inner}>` : inner;
+    let ref = null;
+    if (Node6.isIdentifier(typeInfo.node)) {
+      const name = typeInfo.node.getText();
+      const localDecl = sourceFile.getInterface(name) || sourceFile.getClass(name) || sourceFile.getTypeAlias(name);
+      if (localDecl?.isExported()) {
+        ref = { name, filePath: sourceFile.getFilePath(), isArray: typeInfo.isArray };
+      } else {
+        const resolved = resolveImportedType(name, sourceFile, project);
+        if (resolved && (resolved.kind === "class" || resolved.kind === "interface") && resolved.decl.isExported()) {
+          ref = { name, filePath: resolved.file.getFilePath(), isArray: typeInfo.isArray };
+        }
+      }
+    }
+    return { type, ref };
+  }
+  return null;
+}
 function resolveIdentifierToClassType(node, sourceFile, project, depth) {
   if (!Node6.isIdentifier(node)) return "unknown";
   const name = node.getText();
@@ -2827,17 +3600,52 @@ function resolveBodyQueryResponseRef(typeNode, sourceFile, project) {
     unwrapContainers: true
   });
 }
+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"]);
+function detectStreamElement(method) {
+  const hasSse = method.getDecorators().some((d) => d.getName() === "Sse");
+  let node = method.getReturnTypeNode();
+  node = unwrapNamedContainer(node, /* @__PURE__ */ new Set(["Promise"]));
+  const containerEl = streamContainerElement(node);
+  if (containerEl) {
+    return unwrapNamedContainer(containerEl, STREAM_ENVELOPES) ?? containerEl;
+  }
+  if (hasSse) return node ?? null;
+  return null;
+}
+function streamContainerElement(node) {
+  if (!node || !Node6.isTypeReference(node)) return null;
+  const typeName = node.getTypeName();
+  const name = Node6.isIdentifier(typeName) ? typeName.getText() : "";
+  if (STREAM_CONTAINERS.has(name) || STREAM_CONTAINERS_GENERATOR.has(name)) {
+    return node.getTypeArguments()[0] ?? null;
+  }
+  return null;
+}
+function unwrapNamedContainer(node, names) {
+  if (!node || !Node6.isTypeReference(node)) return node;
+  const typeName = node.getTypeName();
+  const name = Node6.isIdentifier(typeName) ? typeName.getText() : "";
+  if (names.has(name)) {
+    return node.getTypeArguments()[0] ?? node;
+  }
+  return node;
+}
 function extractDtoContract(method, sourceFile, project) {
   let body = extractBodyType(method, sourceFile, project);
   const filterInfo = extractApplyFilterInfo(method, sourceFile, project);
   const query = extractQueryType(method, sourceFile, project);
+  const streamElement = detectStreamElement(method);
+  const isStream = streamElement !== null;
   if (filterInfo && filterInfo.source === "body") {
     const bodyType = "import('@dudousxd/nestjs-filter-client').FilterQueryResult";
     body = body ?? bodyType;
   }
   const paramsType = extractParamsType(method, sourceFile, project);
-  const response = extractResponseType(method, sourceFile, project);
-  if (body === null && query === null && paramsType === null && response === "unknown" && filterInfo === null) {
+  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) {
     return null;
   }
   let bodyRef = null;
@@ -2851,12 +3659,12 @@ function extractDtoContract(method, sourceFile, project) {
       queryRef = resolveBodyQueryResponseRef(param.getTypeNode(), sourceFile, project);
     }
   }
-  const returnTypeNode = method.getReturnTypeNode();
+  const returnTypeNode = isStream ? streamElement : method.getReturnTypeNode();
   if (returnTypeNode) {
     responseRef = resolveBodyQueryResponseRef(returnTypeNode, sourceFile, project);
   }
-  if (!responseRef) {
-    const apiResp = method.getDecorator("ApiResponse");
+  if (!responseRef && !isStream) {
+    const apiResp = method.getDecorators().find((d) => d.getName() === "ApiResponse" && (apiResponseStatus(d) ?? 0) < 400);
     if (apiResp) {
       const args = apiResp.getArguments();
       const optsArg = args[0];
@@ -2898,16 +3706,19 @@ function extractDtoContract(method, sourceFile, project) {
     query,
     body,
     response,
+    error: errorInfo?.type ?? null,
     params: paramsType,
     queryRef,
     bodyRef,
     responseRef,
+    errorRef: errorInfo?.ref ?? null,
     filterFields: filterInfo?.fieldNames ?? null,
     filterFieldTypes: filterInfo?.fieldTypes ?? null,
     filterSource: filterInfo?.source ?? null,
     formWarnings,
     bodySchema,
-    querySchema
+    querySchema,
+    stream: isStream
   };
 }
 function resolveParamClass(method, decoratorName, sourceFile, project) {
@@ -3025,6 +3836,7 @@ function parseDefineContractCall(callExpr) {
   let query = null;
   let body = null;
   let response = "unknown";
+  let error = null;
   let bodyZodText = null;
   let queryZodText = null;
   for (const prop of optsArg.getProperties()) {
@@ -3040,25 +3852,38 @@ function parseDefineContractCall(callExpr) {
       bodyZodText = val.getText();
     } else if (propName === "response") {
       response = zodAstToTs(val);
+    } else if (propName === "error") {
+      error = zodAstToTs(val);
     }
   }
-  return { query, body, response, bodyZodText, queryZodText };
+  return { query, body, response, error, bodyZodText, queryZodText };
 }
 
 // src/discovery/contracts-fast.ts
 async function discoverContractsFast(opts) {
   const { cwd, glob, tsconfig } = opts;
-  const tsconfigPath = tsconfig ? resolve3(tsconfig) : join11(cwd, "tsconfig.json");
-  let project;
+  const tsconfigPath = resolveTsconfigPath(cwd, tsconfig);
+  const project = createDiscoveryProject(tsconfigPath);
+  const files = await fg2(glob, { cwd, absolute: true, onlyFiles: true });
+  for (const f of files) {
+    project.addSourceFileAtPath(f);
+  }
+  bindDiscoveryContext(project, cwd, tsconfigPath);
+  return extractAllRoutes(project);
+}
+function resolveTsconfigPath(cwd, tsconfig) {
+  return tsconfig ? resolve3(tsconfig) : join13(cwd, "tsconfig.json");
+}
+function createDiscoveryProject(tsconfigPath) {
   try {
-    project = new Project3({
+    return new Project3({
       tsConfigFilePath: tsconfigPath,
       skipAddingFilesFromTsConfig: true,
       skipLoadingLibFiles: true,
       skipFileDependencyResolution: true
     });
   } catch {
-    project = new Project3({
+    return new Project3({
       skipAddingFilesFromTsConfig: true,
       skipLoadingLibFiles: true,
       skipFileDependencyResolution: true,
@@ -3069,20 +3894,105 @@ async function discoverContractsFast(opts) {
       }
     });
   }
-  const files = await fg2(glob, { cwd, absolute: true, onlyFiles: true });
-  for (const f of files) {
-    project.addSourceFileAtPath(f);
-  }
-  const routes = [];
+}
+function bindDiscoveryContext(project, cwd, tsconfigPath) {
   setDiscoveryContext(project, {
     projectRoot: cwd,
     tsconfigPaths: loadTsconfigPaths(tsconfigPath)
   });
+}
+function extractRoutesFrom(project, controllerPaths) {
+  const routes = [];
+  for (const path of controllerPaths) {
+    const sourceFile = project.getSourceFile(path);
+    if (sourceFile) routes.push(...extractFromSourceFile(sourceFile, project));
+  }
+  return routes;
+}
+function extractAllRoutes(project) {
+  const routes = [];
   for (const sourceFile of project.getSourceFiles()) {
     routes.push(...extractFromSourceFile(sourceFile, project));
   }
   return routes;
 }
+var PersistentDiscovery = class _PersistentDiscovery {
+  project;
+  cwd;
+  glob;
+  /** Absolute paths of the controllers currently loaded as extraction roots. */
+  controllerPaths = /* @__PURE__ */ new Set();
+  constructor(project, cwd, glob) {
+    this.project = project;
+    this.cwd = cwd;
+    this.glob = glob;
+  }
+  /**
+   * Build the initial persistent Project: create it, glob + add all controllers,
+   * bind the discovery context. Mirrors {@link discoverContractsFast}'s setup.
+   */
+  static async create(opts) {
+    const { cwd, glob, tsconfig } = opts;
+    const tsconfigPath = resolveTsconfigPath(cwd, tsconfig);
+    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 });
+    for (const f of files) {
+      project.addSourceFileAtPath(f);
+      instance.controllerPaths.add(f);
+    }
+    return instance;
+  }
+  /** Run the initial extraction (equivalent to a first `discoverContractsFast`). */
+  discover() {
+    return this.runExtraction();
+  }
+  /**
+   * Re-discover after one or more files changed. Refreshes the changed file(s)
+   * from disk (controllers AND any lazily-loaded DTO/imported files), re-globs
+   * to pick up added/removed controllers, clears the per-Project caches, then
+   * re-extracts. `changedPaths` is a hint; correctness does not depend on it
+   * being exhaustive because re-globbing + refresh-on-presence covers the set.
+   */
+  async rediscover(changedPaths) {
+    if (changedPaths) {
+      for (const p of changedPaths) {
+        const abs = resolve3(p);
+        const sf = this.project.getSourceFile(abs);
+        if (sf) {
+          await sf.refreshFromFileSystem();
+        }
+      }
+    }
+    const globbed = new Set(
+      await fg2(this.glob, { cwd: this.cwd, absolute: true, onlyFiles: true })
+    );
+    for (const f of globbed) {
+      if (!this.controllerPaths.has(f)) {
+        try {
+          this.project.addSourceFileAtPath(f);
+          this.controllerPaths.add(f);
+        } catch {
+        }
+      }
+    }
+    for (const f of this.controllerPaths) {
+      if (!globbed.has(f)) {
+        const sf = this.project.getSourceFile(f);
+        if (sf) this.project.removeSourceFile(sf);
+        this.controllerPaths.delete(f);
+      }
+    }
+    return this.runExtraction();
+  }
+  /** Clear stale per-Project caches, then extract over the controller set. */
+  runExtraction() {
+    clearTypeResolutionCaches(this.project);
+    clearEnumCache(this.project);
+    return extractRoutesFrom(this.project, this.controllerPaths);
+  }
+};
 function decoratorStringArg(decoratorExpr) {
   if (!decoratorExpr) return void 0;
   if (Node8.isStringLiteral(decoratorExpr)) return decoratorExpr.getLiteralValue();
@@ -3138,6 +4048,11 @@ function resolveVerb(method) {
       return { httpMethod: verb, handlerPath: decoratorStringArg(pathArg) ?? "" };
     }
   }
+  const sseDecorator = method.getDecorator("Sse");
+  if (sseDecorator) {
+    const pathArg = sseDecorator.getArguments()[0];
+    return { httpMethod: "GET", handlerPath: decoratorStringArg(pathArg) ?? "" };
+  }
   return null;
 }
 function readAsDecorator(node, label) {
@@ -3180,7 +4095,17 @@ function buildRoute(args) {
   };
 }
 function extractContractRoute(args) {
-  const { cls, method, applyContractDecorator, verb, prefix, className, sourceFile, seenNames } = args;
+  const {
+    cls,
+    method,
+    applyContractDecorator,
+    verb,
+    prefix,
+    className,
+    sourceFile,
+    project,
+    seenNames
+  } = args;
   const firstDecoratorArg = applyContractDecorator.getArguments()[0];
   if (!firstDecoratorArg) return null;
   let contractDef = null;
@@ -3190,18 +4115,19 @@ function extractContractRoute(args) {
     contractDef = parseDefineContractCall(firstDecoratorArg);
   } else if (Node8.isIdentifier(firstDecoratorArg)) {
     const identName = firstDecoratorArg.getText();
-    const varDecl = sourceFile.getVariableDeclaration(identName);
-    if (!varDecl) {
+    const resolvedVar = resolveImportedVariable(identName, sourceFile, project);
+    if (!resolvedVar) {
       console.warn(
-        `[nestjs-codegen/fast] Cannot resolve '${identName}' in ${sourceFile.getFilePath()} (cross-file imports are out-of-scope for v1) \u2014 skipping`
+        `[nestjs-codegen/fast] Cannot resolve contract identifier '${identName}' applied in ${sourceFile.getFilePath()} \u2014 the import could not be followed to a declaration; skipping`
       );
       return null;
     }
+    const { decl: varDecl, file: declFile } = resolvedVar;
     const initializer = varDecl.getInitializer();
     if (!initializer) return null;
     contractDef = parseDefineContractCall(initializer);
     if (contractDef && varDecl.isExported()) {
-      const filePath = sourceFile.getFilePath();
+      const filePath = declFile.getFilePath();
       if (contractDef.body !== null) {
         bodyZodRef = { name: `${identName}.body`, filePath };
       }
@@ -3234,6 +4160,7 @@ function extractContractRoute(args) {
       query: contractDef.query,
       body: contractDef.body,
       response: contractDef.response,
+      error: contractDef.error,
       // Path A: capture both the importable ref and the raw text. The emitter
       // prefers inlining the text (client-safe — re-exporting from a controller
       // would drag server-only deps into the client bundle).
@@ -3265,15 +4192,18 @@ function extractDtoRoute(args) {
       query: dtoContract?.query ?? null,
       body: dtoContract?.body ?? null,
       response: dtoContract?.response ?? "unknown",
+      error: dtoContract?.error ?? null,
       queryRef: dtoContract?.queryRef ?? null,
       bodyRef: dtoContract?.bodyRef ?? null,
       responseRef: dtoContract?.responseRef ?? null,
+      errorRef: dtoContract?.errorRef ?? null,
       filterFields: dtoContract?.filterFields ?? null,
       filterFieldTypes: dtoContract?.filterFieldTypes ?? null,
       filterSource: dtoContract?.filterSource ?? null,
       formWarnings: dtoContract?.formWarnings ?? [],
       bodySchema: dtoContract?.bodySchema ?? null,
-      querySchema: dtoContract?.querySchema ?? null
+      querySchema: dtoContract?.querySchema ?? null,
+      stream: dtoContract?.stream ?? false
     }
   });
 }
@@ -3297,6 +4227,7 @@ function extractFromSourceFile(sourceFile, project) {
         prefix,
         className,
         sourceFile,
+        project,
         seenNames
       }) : extractDtoRoute({
         cls,
@@ -3316,8 +4247,8 @@ function extractFromSourceFile(sourceFile, project) {
 
 // src/watch/lock-file.ts
 import { open } from "fs/promises";
-import { mkdir as mkdir8, readFile as readFile2, unlink } from "fs/promises";
-import { join as join12 } from "path";
+import { mkdir as mkdir10, readFile as readFile2, unlink } from "fs/promises";
+import { join as join14 } from "path";
 var LOCK_FILE = ".watcher.lock";
 function isProcessAlive(pid) {
   try {
@@ -3328,8 +4259,8 @@ function isProcessAlive(pid) {
   }
 }
 async function acquireLock(outDir) {
-  await mkdir8(outDir, { recursive: true });
-  const lockPath = join12(outDir, LOCK_FILE);
+  await mkdir10(outDir, { recursive: true });
+  const lockPath = join14(outDir, LOCK_FILE);
   const lockData = { pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() };
   try {
     const fd = await open(lockPath, "wx");
@@ -3369,7 +4300,7 @@ async function watch(config, onChange) {
   if (lock === null) {
     let holderPid = "unknown";
     try {
-      const raw = await readFile3(join13(config.codegen.outDir, ".watcher.lock"), "utf8");
+      const raw = await readFile3(join15(config.codegen.outDir, ".watcher.lock"), "utf8");
       const data = JSON.parse(raw);
       if (data.pid !== void 0) holderPid = String(data.pid);
     } catch {
@@ -3379,12 +4310,20 @@ async function watch(config, onChange) {
     );
     return NO_OP_WATCHER;
   }
+  let discovery = null;
+  async function getDiscovery() {
+    if (discovery === null) {
+      discovery = await PersistentDiscovery.create({
+        cwd: config.codegen.cwd,
+        glob: config.contracts.glob,
+        ...config.app?.tsconfig ? { tsconfig: config.app.tsconfig } : {}
+      });
+      return discovery;
+    }
+    return discovery;
+  }
   try {
-    const initialRoutes = await discoverContractsFast({
-      cwd: config.codegen.cwd,
-      glob: config.contracts.glob,
-      ...config.app?.tsconfig ? { tsconfig: config.app.tsconfig } : {}
-    });
+    const initialRoutes = (await getDiscovery()).discover();
     await generate(config, initialRoutes);
   } catch (err) {
     console.warn(
@@ -3397,7 +4336,7 @@ async function watch(config, onChange) {
   }
   let pagesDebounceTimer;
   const pagesGlob = config.pages?.glob ?? ".nestjs-codegen-no-pages";
-  const pagesWatcher = chokidar.watch(join13(config.codegen.cwd, pagesGlob), {
+  const pagesWatcher = chokidar.watch(join15(config.codegen.cwd, pagesGlob), {
     ignoreInitial: true,
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
@@ -3423,23 +4362,23 @@ async function watch(config, onChange) {
   pagesWatcher.on("change", schedulePagesRegenerate);
   pagesWatcher.on("unlink", schedulePagesRegenerate);
   let contractsDebounceTimer;
-  const contractsWatcher = chokidar.watch(join13(config.codegen.cwd, config.contracts.glob), {
+  const pendingChangedPaths = /* @__PURE__ */ new Set();
+  const contractsWatcher = chokidar.watch(join15(config.codegen.cwd, config.contracts.glob), {
     ignoreInitial: true,
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
   });
-  function scheduleContractsRegenerate() {
+  function scheduleContractsRegenerate(changedPath) {
+    if (typeof changedPath === "string") pendingChangedPaths.add(changedPath);
     if (contractsDebounceTimer !== void 0) {
       clearTimeout(contractsDebounceTimer);
     }
     contractsDebounceTimer = setTimeout(async () => {
       contractsDebounceTimer = void 0;
+      const changed = [...pendingChangedPaths];
+      pendingChangedPaths.clear();
       try {
-        const routes = await discoverContractsFast({
-          cwd: config.codegen.cwd,
-          glob: config.contracts.glob,
-          ...config.app?.tsconfig ? { tsconfig: config.app.tsconfig } : {}
-        });
+        const routes = await (await getDiscovery()).rediscover(changed);
         await generate(config, routes);
       } catch (err) {
         console.error(
@@ -3450,17 +4389,17 @@ async function watch(config, onChange) {
       onChange?.();
     }, config.contracts.debounceMs);
   }
-  contractsWatcher.on("add", scheduleContractsRegenerate);
-  contractsWatcher.on("change", scheduleContractsRegenerate);
-  contractsWatcher.on("unlink", scheduleContractsRegenerate);
-  const formsWatcher = chokidar.watch(join13(config.codegen.cwd, config.forms.watch), {
+  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), {
     ignoreInitial: true,
     persistent: true,
     awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 }
   });
-  formsWatcher.on("add", scheduleContractsRegenerate);
-  formsWatcher.on("change", scheduleContractsRegenerate);
-  formsWatcher.on("unlink", scheduleContractsRegenerate);
+  formsWatcher.on("add", (p) => scheduleContractsRegenerate(p));
+  formsWatcher.on("change", (p) => scheduleContractsRegenerate(p));
+  formsWatcher.on("unlink", (p) => scheduleContractsRegenerate(p));
   return {
     close: async () => {
       if (pagesDebounceTimer !== void 0) {
@@ -3529,16 +4468,20 @@ function renderTsType(node, ctx) {
 }
 
 // src/index.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 export {
   CodegenError,
   ConfigError,
   VERSION,
   acquireLock,
+  buildMocksFile,
+  buildOpenApiSpec,
   defineConfig,
   discoverContractsFast,
   emitApi,
   emitForms,
+  emitMocks,
+  emitOpenApi,
   emitRoutes,
   extractSchemaFromDto,
   generate,
@@ -3546,6 +4489,8 @@ export {
   renderTsType,
   resolveAdapter,
   resolveConfig,
+  schemaModuleToJsonSchema,
+  schemaNodeToJsonSchema,
   watch
 };
 //# sourceMappingURL=index.js.map