@techspokes/typescript-wsdl-client 0.11.5 → 0.13.0

package/README.md

@@ -13,6 +13,7 @@ Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-re
 - OpenAPI 3.1 specs that mirror your TypeScript types
 - REST gateway over SOAP with automatic request/response transformation
 - CI-friendly deterministic output for safe regeneration in version control
+- WSDL/XSD documentation propagated into generated comments and OpenAPI descriptions
 
 ## Quick Start
 
@@ -57,7 +58,7 @@ curl -X POST http://localhost:3000/get-weather-information \
 
 | Output | Files | Purpose |
 |--------|-------|---------|
-| TypeScript Client | client.ts, types.ts, utils.ts | Typed SOAP operations |
+| TypeScript Client | client.ts, types.ts, utils.ts, operations.ts | Typed SOAP operations and mockable operations interface |
 | OpenAPI 3.1 Spec | openapi.json or .yaml | REST API documentation |
 | Fastify Gateway | plugin.ts, routes/, schemas/ | Production REST handlers |
 | Catalog | catalog.json | Compiled WSDL (debuggable, cacheable) |

package/dist/app/generateApp.js

@@ -454,7 +454,7 @@ function generatePackageJson(appDir, force) {
         dependencies: {
             fastify: "^5.7.4",
             "fastify-plugin": "^5.1.0",
-            soap: "^1.6.5",
+            soap: "^1.7.1",
         },
         devDependencies: {
             tsx: "^4.21.0",

package/dist/client/generateClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateClient.d.ts","sourceRoot":"","sources":["../../src/client/generateClient.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAInE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAsWxE"}
+{"version":3,"file":"generateClient.d.ts","sourceRoot":"","sources":["../../src/client/generateClient.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAInE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QA+WxE"}

package/dist/client/generateClient.js

@@ -34,6 +34,12 @@ import { error, warn } from "../util/cli.js";
  */
 export function generateClient(outFile, compiled) {
     const isValidIdent = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+    const normalizeDocLines = (text) => String(text)
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => line.replace(/\*\//g, "*\\/"));
     const reserved = new Set([
         "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete",
         "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if",
@@ -61,11 +67,13 @@ export function generateClient(outFile, compiled) {
         const inTs = inTypeName ? `T.${inTypeName}` : `any`;
         const outTs = outTypeName ? `T.${outTypeName}` : `any`;
         const secHints = Array.isArray(op.security) && op.security.length ? op.security : [];
+        const opDocLines = op.doc ? normalizeDocLines(op.doc) : [];
+        const opDocStr = opDocLines.length ? `\n   *\n${opDocLines.map(line => `   * ${line}`).join("\n")}` : "";
         const secHintsStr = secHints.length ? `\n   *\n   * Security (WSDL policy hint): ${secHints.join(", ")}` : "";
         const methodTemplate = `
 
   /**
-   * Calls the ${m} operation of the ${clientName}.${secHintsStr}
+   * Calls the ${m} operation of the ${clientName}.${opDocStr}${secHintsStr}
    *
    * @param args - The request arguments for the ${m} operation.
    * @returns A promise resolving to the operation response containing data, headers, response raw XML, and request raw XML.

package/dist/client/generateOperations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateOperations.d.ts","sourceRoot":"","sources":["../../src/client/generateOperations.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAIrE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CA0DnF"}
+{"version":3,"file":"generateOperations.d.ts","sourceRoot":"","sources":["../../src/client/generateOperations.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAIrE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAsEnF"}

package/dist/client/generateOperations.js

@@ -22,6 +22,12 @@ export function generateOperations(outFile, compiled) {
     const ext = compiled.options.imports ?? "bare";
     const suffix = ext === "bare" ? "" : `.${ext}`;
     const clientName = deriveClientName(compiled);
+    const normalizeDocLines = (text) => String(text)
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => line.replace(/\*\//g, "*\\/"));
     // Collect type names used in method signatures for the import statement
     const importedTypes = new Set();
     const methods = [];
@@ -37,7 +43,11 @@ export function generateOperations(outFile, compiled) {
             importedTypes.add(inTypeName);
         if (outTypeName)
             importedTypes.add(outTypeName);
-        methods.push(`  ${op.name}(\n` +
+        const docLines = op.doc ? normalizeDocLines(op.doc) : [];
+        const docBlock = docLines.length > 0
+            ? `  /**\n${docLines.map(line => `   * ${line}`).join("\n")}\n   */\n`
+            : "";
+        methods.push(`${docBlock}  ${op.name}(\n` +
             `    args: ${inTs}\n` +
             `  ): Promise<{ response: ${outTs}; headers: unknown }>;\n`);
     }

package/dist/client/generateTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateTypes.d.ts","sourceRoot":"","sources":["../../src/client/generateTypes.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAGjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QA+IvE"}
+{"version":3,"file":"generateTypes.d.ts","sourceRoot":"","sources":["../../src/client/generateTypes.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAGjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAyLvE"}

package/dist/client/generateTypes.js

@@ -35,6 +35,30 @@ import { error } from "../util/cli.js";
  */
 export function generateTypes(outFile, compiled) {
     const lines = [];
+    const normalizeDocLines = (text) => String(text)
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => line.replace(/\*\//g, "*\\/"));
+    const emitDocBlock = (indent, docText, xsdTag) => {
+        if (!docText && !xsdTag) {
+            return;
+        }
+        lines.push(`${indent}/**`);
+        if (docText) {
+            for (const line of normalizeDocLines(docText)) {
+                lines.push(`${indent} * ${line}`);
+            }
+        }
+        if (xsdTag) {
+            if (docText) {
+                lines.push(`${indent} *`);
+            }
+            lines.push(`${indent} * @xsd ${xsdTag}`);
+        }
+        lines.push(`${indent} */`);
+    };
     // Convenience lookups
     const typeNames = new Set(compiled.types.map((t) => t.name));
     const isValidIdent = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
@@ -45,8 +69,14 @@ export function generateTypes(outFile, compiled) {
     // sort aliases by name to ensure consistent order
     compiled.aliases.sort((a, b) => a.name.localeCompare(b.name));
     for (const a of compiled.aliases) {
-        const ann = a.jsdoc ? `/** @xsd ${a.jsdoc} */\n` : "";
-        lines.push(`${ann}export type ${a.name} = ${a.tsType};`);
+        if (a.doc) {
+            emitDocBlock("", a.doc, a.jsdoc);
+            lines.push(`export type ${a.name} = ${a.tsType};`);
+        }
+        else {
+            const ann = a.jsdoc ? `/** @xsd ${a.jsdoc} */\n` : "";
+            lines.push(`${ann}export type ${a.name} = ${a.tsType};`);
+        }
         lines.push("");
     }
     //
@@ -64,6 +94,9 @@ export function generateTypes(outFile, compiled) {
             typeNames.has(e.tsType));
         const isSimpleContentExtension = !complexBase && (t.elems?.length || 0) === 1 && valueElems.length === 1;
         const baseName = complexBase ?? (isSimpleContentExtension ? valueElems[0].tsType : undefined);
+        if (t.doc) {
+            emitDocBlock("", t.doc);
+        }
         // Header: extend base type if applicable
         if (baseName) {
             lines.push(`export interface ${t.name} extends ${baseName} {`);
@@ -108,9 +141,14 @@ export function generateTypes(outFile, compiled) {
                 type: a.declaredType,
                 use: a.use || "optional",
             };
-            const ann = `  /** @xsd ${JSON.stringify(annObj)} */`;
             lines.push("");
-            lines.push(ann);
+            if (a.doc) {
+                emitDocBlock("  ", a.doc, JSON.stringify(annObj));
+            }
+            else {
+                const ann = `  /** @xsd ${JSON.stringify(annObj)} */`;
+                lines.push(ann);
+            }
             lines.push(`  ${emitPropName(a.name)}${opt}: ${a.tsType};`);
         }
         //
@@ -153,9 +191,14 @@ export function generateTypes(outFile, compiled) {
             if ((e.name === "$value") && (1 < elementsToEmit.length)) {
                 lines.push("");
             }
-            const ann = `  /** @xsd ${JSON.stringify(annObj)} */`;
             lines.push("");
-            lines.push(ann);
+            if (e.doc) {
+                emitDocBlock("  ", e.doc, JSON.stringify(annObj));
+            }
+            else {
+                const ann = `  /** @xsd ${JSON.stringify(annObj)} */`;
+                lines.push(ann);
+            }
             lines.push(`  ${emitPropName(e.name)}${opt}: ${e.tsType}${arr};`);
         }
         lines.push("}");

package/dist/compiler/schemaCompiler.d.ts

@@ -43,6 +43,7 @@ export type CompiledType = {
         tsType: string;
         use?: "required" | "optional";
         declaredType: string;
+        doc?: string;
     }>;
     elems: Array<{
         name: string;
@@ -51,14 +52,17 @@ export type CompiledType = {
         max: number | "unbounded";
         nillable?: boolean;
         declaredType: string;
+        doc?: string;
     }>;
     jsdoc?: string;
+    doc?: string;
     base?: string;
     localAttrs?: Array<{
         name: string;
         tsType: string;
         use?: "required" | "optional";
         declaredType: string;
+        doc?: string;
     }>;
     localElems?: Array<{
         name: string;
@@ -67,6 +71,7 @@ export type CompiledType = {
         max: number | "unbounded";
         nillable?: boolean;
         declaredType: string;
+        doc?: string;
     }>;
 };
 /**
@@ -85,6 +90,7 @@ export type CompiledAlias = {
     tsType: string;
     declared: string;
     jsdoc?: string;
+    doc?: string;
 };
 /**
  * Complete compiled catalog with all types, aliases, operations and metadata
@@ -105,6 +111,7 @@ export type CompiledCatalog = {
     aliases: CompiledAlias[];
     meta: {
         attrSpec: Record<string, string[]>;
+        attrType: Record<string, Record<string, string>>;
         childType: Record<string, Record<string, string>>;
         propMeta: Record<string, Record<string, any>>;
     };
@@ -116,6 +123,7 @@ export type CompiledCatalog = {
         security?: string[];
         inputTypeName?: string;
         outputTypeName?: string;
+        doc?: string;
     }>;
     wsdlTargetNS: string;
     wsdlUri: string;

package/dist/compiler/schemaCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"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"}

package/dist/compiler/schemaCompiler.js

@@ -92,6 +92,57 @@ function collectSecurityFromPolicyNodes(policyNodes) {
         visit(p);
     return Array.from(found);
 }
+function extractNodeText(node) {
+    if (node == null) {
+        return "";
+    }
+    if (typeof node === "string" || typeof node === "number" || typeof node === "boolean") {
+        return String(node);
+    }
+    if (Array.isArray(node)) {
+        return node.map(extractNodeText).join(" ");
+    }
+    if (typeof node === "object") {
+        const parts = [];
+        if (node["#text"] != null) {
+            parts.push(extractNodeText(node["#text"]));
+        }
+        for (const [k, v] of Object.entries(node)) {
+            if ("#text" === k || k.startsWith("@_")) {
+                continue;
+            }
+            parts.push(extractNodeText(v));
+        }
+        return parts.join(" ");
+    }
+    return "";
+}
+function normalizeDocText(text) {
+    const compact = text
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .map(line => line.trim())
+        .filter(Boolean)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return compact || undefined;
+}
+function extractDirectDocumentation(node) {
+    const docs = getChildrenWithLocalName(node, "documentation");
+    const merged = docs
+        .map(extractNodeText)
+        .join(" ");
+    return normalizeDocText(merged);
+}
+function extractAnnotationDocumentation(node) {
+    const annotations = getChildrenWithLocalName(node, "annotation");
+    const docs = annotations.flatMap(a => getChildrenWithLocalName(a, "documentation"));
+    const merged = docs
+        .map(extractNodeText)
+        .join(" ");
+    return normalizeDocText(merged);
+}
 /**
  * Compile a WSDL catalog into an internal representation (CompiledCatalog).
  * Steps:
@@ -136,6 +187,7 @@ export function compileCatalog(cat, options) {
     const inProgress = new Set();
     // meta accumulators
     const attrSpec = {};
+    const attrType = {};
     const childType = {};
     const propMeta = {};
     /** Compile a simpleType node to TS */
@@ -171,7 +223,14 @@ export function compileCatalog(cat, options) {
             return present;
         }
         const { tsType, declared, jsdoc } = compileSimpleTypeNode(sNode, schemaNS, prefixes);
-        const alias = { name: pascal(name), ns: schemaNS, tsType, declared, jsdoc };
+        const alias = {
+            name: pascal(name),
+            ns: schemaNS,
+            tsType,
+            declared,
+            jsdoc,
+            doc: extractAnnotationDocumentation(sNode),
+        };
         aliasMap.set(key, alias);
         return alias;
     }
@@ -220,6 +279,7 @@ export function compileCatalog(cat, options) {
         }
         inProgress.add(rawKey);
         const outName = pascal(name);
+        const typeDoc = extractAnnotationDocumentation(cnode);
         const key = `${schemaNS}|${outName}`;
         // hoisted helpers for merging and collecting
         const mergeAttrs = (into, list) => {
@@ -266,7 +326,8 @@ export function compileCatalog(cat, options) {
                         name: an,
                         tsType: r.tsType,
                         use: a["@_use"] === "required" ? "required" : "optional",
-                        declaredType: r.declared
+                        declaredType: r.declared,
+                        doc: extractAnnotationDocumentation(a),
                     });
                 }
                 else {
@@ -278,7 +339,8 @@ export function compileCatalog(cat, options) {
                         name: an,
                         tsType: r.tsType,
                         use: a["@_use"] === "required" ? "required" : "optional",
-                        declaredType: r.declared
+                        declaredType: r.declared,
+                        doc: extractAnnotationDocumentation(a),
                     });
                 }
             }
@@ -309,18 +371,35 @@ export function compileCatalog(cat, options) {
                             min,
                             max,
                             nillable,
-                            declaredType: `{${schemaNS}}${rec.name}`
+                            declaredType: `{${schemaNS}}${rec.name}`,
+                            doc: extractAnnotationDocumentation(e),
                         });
                     }
                     else if (inlineSimple) {
                         const r = compileSimpleTypeNode(inlineSimple, schemaNS, prefixes);
-                        out.push({ name: propName || nameOrRef, tsType: r.tsType, min, max, nillable, declaredType: r.declared });
+                        out.push({
+                            name: propName || nameOrRef,
+                            tsType: r.tsType,
+                            min,
+                            max,
+                            nillable,
+                            declaredType: r.declared,
+                            doc: extractAnnotationDocumentation(e),
+                        });
                     }
                     else {
                         const t = e["@_type"] || e["@_ref"];
                         const q = t ? resolveQName(t, schemaNS, prefixes) : { ns: XS, local: "string" };
                         const r = resolveTypeRef(q, schemaNS, prefixes);
-                        out.push({ name: propName || nameOrRef, tsType: r.tsType, min, max, nillable, declaredType: r.declared });
+                        out.push({
+                            name: propName || nameOrRef,
+                            tsType: r.tsType,
+                            min,
+                            max,
+                            nillable,
+                            declaredType: r.declared,
+                            doc: extractAnnotationDocumentation(e),
+                        });
                     }
                 }
                 // recurse into nested compositor groups
@@ -340,6 +419,9 @@ export function compileCatalog(cat, options) {
             const newElems = collectParticles(outName, cnode);
             mergeAttrs(present.attrs, newAttrs);
             mergeElems(present.elems, newElems);
+            if (!present.doc && typeDoc) {
+                present.doc = typeDoc;
+            }
             // Remove from inProgress since we're done with this cycle
             inProgress.delete(rawKey);
             return present;
@@ -378,6 +460,7 @@ export function compileCatalog(cat, options) {
                     ns: schemaNS,
                     attrs,
                     elems,
+                    doc: typeDoc,
                     base: baseName,
                     localAttrs: locals,
                     localElems
@@ -408,7 +491,7 @@ export function compileCatalog(cat, options) {
                         declaredType: r.declared,
                     }]);
                 mergeAttrs(attrs, collectAttributes(scNode));
-                const result = { name: outName, ns: schemaNS, attrs, elems };
+                const result = { name: outName, ns: schemaNS, attrs, elems, doc: typeDoc };
                 compiledMap.set(key, result);
                 inProgress.delete(rawKey);
                 return result;
@@ -423,7 +506,7 @@ export function compileCatalog(cat, options) {
         // Attributes + particles
         mergeAttrs(attrs, collectAttributes(cnode));
         mergeElems(elems, collectParticles(outName, cnode));
-        const result = { name: outName, ns: schemaNS, attrs, elems };
+        const result = { name: outName, ns: schemaNS, attrs, elems, doc: typeDoc };
         compiledMap.set(key, result);
         inProgress.delete(rawKey);
         return result;
@@ -431,6 +514,7 @@ export function compileCatalog(cat, options) {
     // Helper: compile a global element into a surface type (wrapper)
     function compileElementAsType(name, enode, schemaNS, prefixes) {
         const outName = pascal(name);
+        const elementDoc = extractAnnotationDocumentation(enode);
         const key = `${schemaNS}|${outName}`;
         const present = compiledMap.get(key);
         if (present)
@@ -447,6 +531,7 @@ export function compileCatalog(cat, options) {
                 ns: schemaNS,
                 attrs: [],
                 elems: [{ name: "$value", tsType: r.tsType, min: 0, max: 1, nillable: false, declaredType: r.declared }],
+                doc: elementDoc,
             };
             compiledMap.set(key, t);
             return t;
@@ -469,6 +554,7 @@ export function compileCatalog(cat, options) {
                             nillable: false,
                             declaredType: label
                         }],
+                    doc: elementDoc,
                 };
                 compiledMap.set(key, t);
                 return t;
@@ -484,10 +570,13 @@ export function compileCatalog(cat, options) {
                     const existingAlias = aliasMap.get(aliasKey);
                     const declared = `{${base.ns}}${base.name}`;
                     if (!existingAlias) {
-                        aliasMap.set(aliasKey, { name: outName, ns: schemaNS, tsType: base.name, declared });
+                        aliasMap.set(aliasKey, { name: outName, ns: schemaNS, tsType: base.name, declared, doc: elementDoc });
                     }
                     else {
                         // if an alias exists but points elsewhere, keep the first one (stable) and ignore
+                        if (!existingAlias.doc && elementDoc) {
+                            existingAlias.doc = elementDoc;
+                        }
                     }
                 }
                 // Return base so callers have a CompiledType, but do not duplicate in compiledMap for wrapper
@@ -508,13 +597,14 @@ export function compileCatalog(cat, options) {
                             nillable: false,
                             declaredType: `{${a.ns}}${q.local}`
                         }],
+                    doc: elementDoc,
                 };
                 compiledMap.set(key, t);
                 return t;
             }
         }
         // default empty wrapper
-        const t = { name: outName, ns: schemaNS, attrs: [], elems: [] };
+        const t = { name: outName, ns: schemaNS, attrs: [], elems: [], doc: elementDoc };
         compiledMap.set(key, t);
         return t;
     }
@@ -536,9 +626,28 @@ export function compileCatalog(cat, options) {
     // emit lists
     const typesList = Array.from(compiledMap.values());
     const aliasList = Array.from(aliasMap.values());
+    // Build alias resolution map for simple type aliases (e.g. YesNoType -> '"Yes" | "No"')
+    const aliasResolve = new Map();
+    for (const a of aliasList) {
+        if (a.tsType && a.tsType !== a.name) {
+            aliasResolve.set(a.name, a.tsType);
+        }
+    }
     // meta
     for (const t of typesList) {
         attrSpec[t.name] = (t.attrs || []).map(a => a.name);
+        const attrMap = {};
+        for (const a of t.attrs || []) {
+            let tsType = typeof a.tsType === "string" ? a.tsType : "string";
+            // Resolve alias names to their underlying TS types for mock data generation
+            if (aliasResolve.has(tsType)) {
+                tsType = aliasResolve.get(tsType);
+            }
+            attrMap[a.name] = tsType;
+        }
+        if (Object.keys(attrMap).length > 0) {
+            attrType[t.name] = attrMap;
+        }
         const child = {};
         const meta = {};
         for (const e of t.elems || []) {
@@ -561,6 +670,9 @@ export function compileCatalog(cat, options) {
                 childType[a.name] = childType[a.tsType];
                 propMeta[a.name] = propMeta[a.tsType];
                 attrSpec[a.name] = attrSpec[a.tsType];
+                if (a.tsType in attrType) {
+                    attrType[a.name] = attrType[a.tsType];
+                }
             }
         }
     }
@@ -629,10 +741,11 @@ export function compileCatalog(cat, options) {
         const outMsg = findMessage(getFirstWithLocalName(po, "output")?.["@_message"]);
         const inputElement = elementOfMessage(inMsg);
         const outputElement = elementOfMessage(outMsg);
+        const doc = extractDirectDocumentation(po);
         // Derive TypeScript type names from element local names
         const inputTypeName = inputElement ? pascal(inputElement.local) : undefined;
         const outputTypeName = outputElement ? pascal(outputElement.local) : undefined;
-        return { name, soapAction: bOps.get(name) || "", inputElement, outputElement, inputTypeName, outputTypeName };
+        return { name, soapAction: bOps.get(name) || "", inputElement, outputElement, inputTypeName, outputTypeName, doc };
     })
         .filter((x) => x != null));
     // --- WS-Policy: scan for security requirements (inline policies only) ---
@@ -664,7 +777,7 @@ export function compileCatalog(cat, options) {
         options: options,
         types: typesList,
         aliases: aliasList,
-        meta: { attrSpec, childType, propMeta },
+        meta: { attrSpec, attrType, childType, propMeta },
         operations: ops,
         wsdlTargetNS: defs?.["@_targetNamespace"] || "",
         serviceName,

package/dist/gateway/generators.d.ts

@@ -36,6 +36,8 @@ export interface OperationMetadata {
     clientMethodName?: string;
     requestTypeName?: string;
     responseTypeName?: string;
+    /** When true, response schema is omitted from route registration to avoid fast-json-stringify stack overflow on deeply nested $ref graphs */
+    skipResponseSchema?: boolean;
 }
 /**
  * Emits Fastify-compatible operation schema files

package/dist/gateway/generators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"AAcA,OAAO,EAAC,KAAK,UAAU,EAAE,KAAK,eAAe,EAA6C,MAAM,cAAc,CAAC;AAE/G;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6BxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,0BAA0B,EAAE,MAAM,EAAE,EACpC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,GAAG,EACvH,UAAU,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,EACnC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACnC,iBAAiB,EAAE,CA2HrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,EAAE,EAC/B,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,IAAI,CA2CN;AAqCD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,GAAG,GACZ,IAAI,CA4ON;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,IAAI,CAwFN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,IAAI,CA6BN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,EAAE,EAC/B,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,GAAG,GACZ,IAAI,CAkGN"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"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"}