@techspokes/typescript-wsdl-client 0.6.2 → 0.7.0

package/dist/cli.js

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
+/**
+ * CLI Entry Point for TypeScript WSDL Client Generator
+ *
+ * This file implements the command-line interface for the wsdl-tsc tool, which generates
+ * fully-typed TypeScript SOAP clients from WSDL/XSD schemas. The CLI supports two main commands:
+ *
+ * 1. Default command (wsdl-tsc): Generates TypeScript client code from WSDL
+ * 2. OpenAPI subcommand (wsdl-tsc openapi): Generates OpenAPI 3.1 specifications from WSDL
+ *
+ * The CLI is built using yargs for argument parsing and provides extensive options for
+ * customizing the code generation process, including TypeScript output configurations and
+ * OpenAPI specification details.
+ */
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 import fs from "node:fs";
@@ -9,7 +22,216 @@ import { emitTypes } from "./emit/typesEmitter.js";
 import { emitUtils } from "./emit/utilsEmitter.js";
 import { emitCatalog } from "./emit/catalogEmitter.js";
 import { emitClient } from "./emit/clientEmitter.js";
-const argv = await yargs(hideBin(process.argv))
+import { generateOpenAPI } from "./openapi/generateOpenAPI.js";
+import { runGenerationPipeline } from "./pipeline.js";
+// Process command line arguments, removing the first two elements (node executable and script path)
+const rawArgs = hideBin(process.argv);
+/**
+ * Command handler for "openapi" subcommand
+ *
+ * This branch handles the OpenAPI generation mode, which creates OpenAPI 3.1 specifications
+ * from either a direct WSDL source or a pre-compiled catalog.json file.
+ */
+if (rawArgs[0] === "openapi") {
+    const openapiArgv = await yargs(rawArgs.slice(1))
+        .version(false)
+        .scriptName("wsdl-tsc openapi")
+        .usage("$0 --wsdl <file|url> --out <openapi.(json|yaml)> [options]")
+        .option("wsdl", { type: "string", desc: "Path or URL to the WSDL (exclusive with --catalog)" })
+        .option("catalog", { type: "string", desc: "Existing compiled catalog.json (exclusive with --wsdl)" })
+        .option("out", { type: "string", demandOption: true, desc: "Output path (base or with extension)" })
+        .option("format", {
+        type: "string",
+        choices: ["json", "yaml", "both"],
+        desc: "Output format: json|yaml|both (default json)"
+    })
+        .option("yaml", { type: "boolean", default: false, desc: "[DEPRECATED] Use --format yaml or both" })
+        .option("title", { type: "string", desc: "API title (defaults to derived service name)" })
+        .option("version", { type: "string", desc: "API version for info.version (default 0.0.0)" })
+        .option("servers", { type: "string", desc: "Comma-separated server URLs" })
+        .option("basePath", { type: "string", desc: "Base path prefix added before operation segments (e.g. /v1/soap)" })
+        .option("pathStyle", {
+        type: "string",
+        choices: ["kebab", "asis", "lower"],
+        default: "kebab",
+        desc: "Path segment style applied to operation names"
+    })
+        .option("method", {
+        type: "string",
+        choices: ["post", "get", "put", "patch", "delete"],
+        default: "post",
+        desc: "Default HTTP method for all operations (can be overridden via --ops)"
+    })
+        .option("security", { type: "string", desc: "Path to security.json configuration" })
+        .option("tags", { type: "string", desc: "Path to tags.json mapping operation name -> tag" })
+        .option("ops", {
+        type: "string",
+        desc: "Path to ops.json per-operation overrides (method, deprecated, summary, description)"
+    })
+        .option("closedSchemas", {
+        type: "boolean",
+        default: false,
+        desc: "Emit additionalProperties:false for object schemas"
+    })
+        .option("pruneUnusedSchemas", {
+        type: "boolean",
+        default: false,
+        desc: "Emit only schemas reachable from operations"
+    })
+        .option("validate", { type: "boolean", default: true, desc: "Validate generated document (always on unless false)" })
+        .option("no-validate", { type: "boolean", default: false, desc: "Alias for --validate=false" })
+        .option("tag-style", {
+        type: "string",
+        choices: ["default", "first", "service"],
+        default: "default",
+        desc: "Heuristic for inferring tags when no --tags map provided"
+    })
+        .strict()
+        .help()
+        .parse();
+    // Show deprecation warning for the legacy --yaml option
+    if (openapiArgv.yaml && !openapiArgv.format) {
+        console.warn("[deprecation] --yaml is deprecated; use --format yaml or --format both");
+    }
+    // Handle the no-validate flag which overrides the validate option
+    if (openapiArgv["no-validate"]) {
+        openapiArgv.validate = false;
+    }
+    // Validate that either --wsdl or --catalog is provided, but not both
+    if (!openapiArgv.wsdl && !openapiArgv.catalog) {
+        console.error("Error: either --wsdl or --catalog must be provided for openapi generation.");
+        process.exit(1);
+    }
+    if (openapiArgv.wsdl && openapiArgv.catalog) {
+        console.error("Error: provide only one of --wsdl or --catalog, not both.");
+        process.exit(1);
+    }
+    // Parse server URLs from comma-separated string
+    const servers = (openapiArgv.servers ? String(openapiArgv.servers).split(",").map(s => s.trim()).filter(Boolean) : []);
+    // Determine output format, with backwards compatibility for the --yaml flag
+    const inferredFormat = openapiArgv.format || (openapiArgv.yaml ? "yaml" : undefined);
+    // Call the OpenAPI generator with the parsed options
+    await generateOpenAPI({
+        wsdl: openapiArgv.wsdl,
+        catalogFile: openapiArgv.catalog,
+        outFile: openapiArgv.out,
+        title: openapiArgv.title,
+        version: openapiArgv.version,
+        servers,
+        basePath: openapiArgv.basePath,
+        pathStyle: openapiArgv.pathStyle,
+        defaultMethod: openapiArgv.method,
+        securityConfigFile: openapiArgv.security,
+        tagsFile: openapiArgv.tags,
+        opsFile: openapiArgv.ops,
+        closedSchemas: openapiArgv.closedSchemas,
+        pruneUnusedSchemas: openapiArgv.pruneUnusedSchemas,
+        format: inferredFormat,
+        skipValidate: openapiArgv.validate === false,
+        tagStyle: openapiArgv["tag-style"],
+    });
+    console.log(`✅ OpenAPI generation complete (${inferredFormat || 'json'})`);
+    process.exit(0);
+}
+if (rawArgs[0] === "pipeline") {
+    const pipelineArgv = await yargs(rawArgs.slice(1))
+        .version(false)
+        .scriptName("wsdl-tsc pipeline")
+        .usage("$0 --wsdl <file|url> --out <dir> [options]")
+        .option("wsdl", { type: "string", demandOption: true, desc: "Path or URL to the WSDL" })
+        .option("out", { type: "string", demandOption: true, desc: "Output directory for TypeScript artifacts" })
+        .option("clean", {
+        type: "boolean",
+        default: false,
+        desc: "Remove existing contents of --out before generation (safety: will refuse if --out is project root)"
+    })
+        // Compiler flags
+        .option("imports", { type: "string", choices: ["js", "ts", "bare"], default: "js" })
+        .option("catalog", { type: "boolean", default: true })
+        .option("attributes-key", { type: "string", default: "$attributes" })
+        .option("int64-as", { type: "string", choices: ["string", "number", "bigint"], default: "string" })
+        .option("bigint-as", { type: "string", choices: ["string", "number"], default: "string" })
+        .option("decimal-as", { type: "string", choices: ["string", "number"], default: "string" })
+        .option("date-as", { type: "string", choices: ["string", "Date"], default: "string" })
+        .option("choice", { type: "string", choices: ["all-optional", "union"], default: "all-optional" })
+        .option("fail-on-unresolved", { type: "boolean", default: false })
+        .option("nillable-as-optional", { type: "boolean", default: false })
+        // OpenAPI flags
+        .option("openapi-out", { type: "string", desc: "Output base or file for OpenAPI (if omitted chooses openapi.json)" })
+        .option("format", { type: "string", choices: ["json", "yaml", "both"], desc: "OpenAPI output format (default json)" })
+        .option("yaml", { type: "boolean", default: false, desc: "[DEPRECATED] Use --format yaml or both" })
+        .option("validate", { type: "boolean", default: true, desc: "Validate OpenAPI output" })
+        .option("no-validate", { type: "boolean", default: false, desc: "Alias for --validate=false" })
+        .option("tag-style", { type: "string", choices: ["default", "first", "service"], default: "default" })
+        .option("servers", { type: "string" })
+        .option("basePath", { type: "string" })
+        .option("pathStyle", { type: "string", choices: ["kebab", "asis", "lower"], default: "kebab" })
+        .option("method", { type: "string", choices: ["post", "get", "put", "patch", "delete"], default: "post" })
+        .option("security", { type: "string" })
+        .option("tags", { type: "string" })
+        .option("ops", { type: "string" })
+        .option("closedSchemas", { type: "boolean", default: false })
+        .option("pruneUnusedSchemas", { type: "boolean", default: false })
+        .strict()
+        .help()
+        .parse();
+    if (pipelineArgv.yaml && !pipelineArgv.format) {
+        console.warn("[deprecation] --yaml is deprecated; use --format yaml or --format both");
+    }
+    if (pipelineArgv["no-validate"]) {
+        pipelineArgv.validate = false;
+    }
+    if (pipelineArgv.clean) {
+        const resolvedOut = path.resolve(String(pipelineArgv.out));
+        const projectRoot = path.resolve(process.cwd());
+        if (resolvedOut === projectRoot) {
+            console.error("Refusing to clean project root. Choose a subdirectory for --out.");
+            process.exit(2);
+        }
+        if (fs.existsSync(resolvedOut)) {
+            fs.rmSync(resolvedOut, { recursive: true, force: true });
+        }
+    }
+    const servers = (pipelineArgv.servers ? String(pipelineArgv.servers).split(",").map(s => s.trim()).filter(Boolean) : []);
+    const format = pipelineArgv.format || (pipelineArgv.yaml ? "yaml" : undefined);
+    await runGenerationPipeline({
+        wsdl: pipelineArgv.wsdl,
+        outDir: pipelineArgv.out,
+        compiler: {
+            imports: pipelineArgv.imports,
+            catalog: pipelineArgv.catalog,
+            attributesKey: pipelineArgv["attributes-key"],
+            primitive: {
+                int64As: pipelineArgv["int64-as"],
+                bigIntegerAs: pipelineArgv["bigint-as"],
+                decimalAs: pipelineArgv["decimal-as"],
+                dateAs: pipelineArgv["date-as"],
+            },
+            choice: pipelineArgv.choice,
+            failOnUnresolved: pipelineArgv["fail-on-unresolved"],
+            nillableAsOptional: pipelineArgv["nillable-as-optional"],
+        },
+        openapi: {
+            outFile: pipelineArgv["openapi-out"],
+            format,
+            skipValidate: pipelineArgv.validate === false,
+            tagStyle: pipelineArgv["tag-style"],
+            servers,
+            basePath: pipelineArgv.basePath,
+            pathStyle: pipelineArgv.pathStyle,
+            defaultMethod: pipelineArgv.method,
+            securityConfigFile: pipelineArgv.security,
+            tagsFile: pipelineArgv.tags,
+            opsFile: pipelineArgv.ops,
+            closedSchemas: pipelineArgv.closedSchemas,
+            pruneUnusedSchemas: pipelineArgv.pruneUnusedSchemas,
+        }
+    });
+    console.log(`✅ Pipeline complete (format=${format || 'json'})`);
+    process.exit(0);
+}
+// ---------- Original generation CLI (unchanged) ----------
+const argv = await yargs(rawArgs)
     .scriptName("wsdl-tsc")
     .option("wsdl", {
     type: "string",

package/dist/compiler/schemaCompiler.d.ts

@@ -1,9 +1,40 @@
+/**
+ * Schema Compiler for TypeScript WSDL Client Generator
+ *
+ * This module transforms the raw WSDL and XSD schema documents into a structured catalog
+ * of TypeScript-ready types, aliases, operations, and metadata. It handles complex
+ * type resolution, namespace management, name conflicts, inheritance, and other
+ * XML Schema complexities.
+ *
+ * The compiler produces a unified representation that serves as the foundation for
+ * generating TypeScript interfaces, type aliases, and SOAP client methods.
+ */
 import type { CompilerOptions } from "../config.js";
 import type { WsdlCatalog } from "../loader/wsdlLoader.js";
+/**
+ * Qualified name with namespace and local part
+ *
+ * @interface QName
+ * @property {string} ns - Namespace URI
+ * @property {string} local - Local name within the namespace
+ */
 export type QName = {
     ns: string;
     local: string;
 };
+/**
+ * Represents a compiled complex type with attributes and elements
+ *
+ * @interface CompiledType
+ * @property {string} name - TypeScript name for the type
+ * @property {string} ns - Namespace URI where the type was defined
+ * @property {Array<Object>} attrs - XML attributes of this type
+ * @property {Array<Object>} elems - Child elements of this type
+ * @property {string} [jsdoc] - Documentation for the type
+ * @property {string} [base] - Base type name for extension/inheritance
+ * @property {Array<Object>} [localAttrs] - Attributes added in extension (not inherited)
+ * @property {Array<Object>} [localElems] - Elements added in extension (not inherited)
+ */
 export type CompiledType = {
     name: string;
     ns: string;
@@ -38,6 +69,16 @@ export type CompiledType = {
         declaredType: string;
     }>;
 };
+/**
+ * Represents a compiled type alias (simple type or restricted type)
+ *
+ * @interface CompiledAlias
+ * @property {string} name - TypeScript name for the alias
+ * @property {string} ns - Namespace URI where the alias was defined
+ * @property {string} tsType - Resolved TypeScript type
+ * @property {string} declared - Original qualified name as declared
+ * @property {string} [jsdoc] - Documentation for the alias
+ */
 export type CompiledAlias = {
     name: string;
     ns: string;
@@ -45,6 +86,19 @@ export type CompiledAlias = {
     declared: string;
     jsdoc?: string;
 };
+/**
+ * Complete compiled catalog with all types, aliases, operations and metadata
+ *
+ * @interface CompiledCatalog
+ * @property {CompilerOptions} options - Original compiler options
+ * @property {CompiledType[]} types - Complex types (interfaces)
+ * @property {CompiledAlias[]} aliases - Named simple types (type aliases)
+ * @property {Object} meta - Additional metadata for code generation
+ * @property {Array<Object>} operations - SOAP operations from the WSDL
+ * @property {string} wsdlTargetNS - Target namespace of the WSDL
+ * @property {string} wsdlUri - URI of the WSDL document
+ * @property {string} [serviceName] - Name of the SOAP service if available
+ */
 export type CompiledCatalog = {
     options: CompilerOptions;
     types: CompiledType[];

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

@@ -1 +1 @@
-{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AAIzD,MAAM,MAAM,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;QAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IAEH,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;QAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;KAC/C,CAAC;IACF,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,KAAK,CAAC;QACrB,aAAa,CAAC,EAAE,KAAK,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC,CAAC;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AA6DF;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,GAAG,eAAe,CAohB1F"}
+{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"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"}

package/dist/compiler/schemaCompiler.js

@@ -1,10 +1,28 @@
 import { getChildrenWithLocalName, getFirstWithLocalName, normalizeArray, pascal, resolveQName, } from "../util/tools.js";
 import { xsdToTsPrimitive } from "../xsd/primitives.js";
+// XML Schema namespace constant
 const XS = "http://www.w3.org/2001/XMLSchema";
+/**
+ * Creates a string key from a qualified name
+ * Format: {namespace}localName
+ *
+ * @param {QName} q - Qualified name to convert
+ * @returns {string} - String representation of the qualified name
+ */
 function qkey(q) {
     return `{${q.ns}}${q.local}`;
 }
-/** Inline complex type naming */
+/**
+ * Generates a name for an inline complex type
+ *
+ * This function creates appropriate TypeScript names for anonymous types
+ * that are defined inline within element declarations.
+ *
+ * @param {string} parentTypeName - Name of the parent type
+ * @param {string} [propName] - Name of the property containing the inline type
+ * @param {number|"unbounded"} [_max] - Maximum occurrence (unused but kept for API compatibility)
+ * @returns {string} - Generated TypeScript name for the inline type
+ */
 function makeInlineTypeName(parentTypeName, propName, _max) {
     const base = pascal(parentTypeName || "AnonParent");
     const prop = pascal(propName || "");
@@ -14,6 +32,16 @@ function makeInlineTypeName(parentTypeName, propName, _max) {
     return `${base}Anon`;
 }
 // --- Minimal WS-Policy scanning (inline policies only; PolicyReference not resolved) ---
+/**
+ * Extracts security requirements from WS-Policy nodes
+ *
+ * This function scans WS-Policy elements for common security patterns like
+ * UsernameToken, TransportBinding (HTTPS), etc. and returns a list of
+ * security requirements found.
+ *
+ * @param {any[]} policyNodes - Array of policy nodes to analyze
+ * @returns {string[]} - Array of security requirement identifiers
+ */
 function collectSecurityFromPolicyNodes(policyNodes) {
     const found = new Set();
     const targets = new Set([
@@ -217,14 +245,24 @@ export function compileCatalog(cat, options) {
                 if (inlineSimple) {
                     // inline enumeration or restriction inside attribute
                     const r = compileSimpleTypeNode(inlineSimple, schemaNS, prefixes);
-                    out.push({ name: an, tsType: r.tsType, use: a["@_use"] === "required" ? "required" : "optional", declaredType: r.declared });
+                    out.push({
+                        name: an,
+                        tsType: r.tsType,
+                        use: a["@_use"] === "required" ? "required" : "optional",
+                        declaredType: r.declared
+                    });
                 }
                 else {
                     // named type or default xs:string
                     const t = a["@_type"];
                     const q = t ? resolveQName(t, schemaNS, prefixes) : { ns: XS, local: "string" };
                     const r = resolveTypeRef(q, schemaNS, prefixes);
-                    out.push({ name: an, tsType: r.tsType, use: a["@_use"] === "required" ? "required" : "optional", declaredType: r.declared });
+                    out.push({
+                        name: an,
+                        tsType: r.tsType,
+                        use: a["@_use"] === "required" ? "required" : "optional",
+                        declaredType: r.declared
+                    });
                 }
             }
             return out;
@@ -248,7 +286,14 @@ export function compileCatalog(cat, options) {
                     if (inlineComplex) {
                         const inlineName = makeInlineTypeName(ownerTypeName, propName || nameOrRef, max);
                         const rec = getOrCompileComplex(inlineName, inlineComplex, schemaNS, prefixes);
-                        out.push({ name: propName || nameOrRef, tsType: rec.name, min, max, nillable, declaredType: `{${schemaNS}}${rec.name}` });
+                        out.push({
+                            name: propName || nameOrRef,
+                            tsType: rec.name,
+                            min,
+                            max,
+                            nillable,
+                            declaredType: `{${schemaNS}}${rec.name}`
+                        });
                     }
                     else if (inlineSimple) {
                         const r = compileSimpleTypeNode(inlineSimple, schemaNS, prefixes);
@@ -314,7 +359,15 @@ export function compileCatalog(cat, options) {
                 const localElems = collectParticles(outName, node);
                 attrs.push(...locals);
                 elems.push(...localElems);
-                const result = { name: outName, ns: schemaNS, attrs, elems, base: baseName, localAttrs: locals, localElems };
+                const result = {
+                    name: outName,
+                    ns: schemaNS,
+                    attrs,
+                    elems,
+                    base: baseName,
+                    localAttrs: locals,
+                    localElems
+                };
                 compiledMap.set(key, result);
                 inProgress.delete(key);
                 return result;
@@ -394,7 +447,14 @@ export function compileCatalog(cat, options) {
                     name: outName,
                     ns: schemaNS,
                     attrs: [],
-                    elems: [{ name: "$value", tsType: xsdToTsPrimitive(label, options?.primitive), min: 0, max: 1, nillable: false, declaredType: label }],
+                    elems: [{
+                            name: "$value",
+                            tsType: xsdToTsPrimitive(label, options?.primitive),
+                            min: 0,
+                            max: 1,
+                            nillable: false,
+                            declaredType: label
+                        }],
                 };
                 compiledMap.set(key, t);
                 return t;
@@ -426,7 +486,14 @@ export function compileCatalog(cat, options) {
                     name: outName,
                     ns: schemaNS,
                     attrs: [],
-                    elems: [{ name: "$value", tsType: a.name, min: 0, max: 1, nillable: false, declaredType: `{${a.ns}}${q.local}` }],
+                    elems: [{
+                            name: "$value",
+                            tsType: a.name,
+                            min: 0,
+                            max: 1,
+                            nillable: false,
+                            declaredType: `{${a.ns}}${q.local}`
+                        }],
                 };
                 compiledMap.set(key, t);
                 return t;

package/dist/config.d.ts

@@ -1,6 +1,29 @@
+/**
+ * Configuration Options for TypeScript WSDL Client Generator
+ *
+ * This module defines the configuration interface and default values for the WSDL-to-TypeScript
+ * compilation process. It centralizes all compiler options that can be customized by users
+ * through the CLI or programmatic API. These options control everything from output formatting
+ * to type mapping strategies.
+ *
+ * The configuration follows a "safe defaults" philosophy, prioritizing correctness and
+ * data integrity over convenience, while still allowing users to override when needed.
+ */
 import type { PrimitiveOptions } from "./xsd/primitives.js";
 /**
  * Options to control WSDL-to-TypeScript compilation behavior.
+ *
+ * @interface CompilerOptions
+ * @property {string} wsdl - Path/URL of the source WSDL (from --wsdl)
+ * @property {string} out - Output directory (from --out)
+ * @property {"js"|"ts"|"bare"} imports - Import-extension mode for generated imports (from --imports)
+ * @property {boolean} catalog - Whether to emit catalog.json file with compiled catalog object
+ * @property {PrimitiveOptions} primitive - Low-level mapping of XSD primitives
+ * @property {"all-optional"|"union"} [choice] - How to represent XML <choice> elements
+ * @property {boolean} [failOnUnresolved] - Whether to emit errors for unresolved type references
+ * @property {string} [attributesKey] - Attribute bag key for the runtime mapper
+ * @property {string} [clientName] - Override the generated client class name
+ * @property {boolean} [nillableAsOptional] - Whether to emit nillable elements as optional properties
  */
 export type CompilerOptions = {
     /** Path/URL of the source WSDL (from --wsdl) */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,SAAS,EAAE,gBAAgB,CAAC;IAC5B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC;IAClC,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,+CAA+C,EAAE,eAgB7D,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,SAAS,EAAE,gBAAgB,CAAC;IAC5B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC;IAClC,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,+CAA+C,EAAE,eAgB7D,CAAC"}

package/dist/emit/catalogEmitter.d.ts

@@ -1,3 +1,21 @@
 import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+/**
+ * Emits the compiled catalog as a JSON file
+ *
+ * This function writes the complete compiled catalog to a JSON file, preserving all
+ * type definitions, operation information, and metadata in a structured format.
+ * The output is useful for introspection, debugging, and as input for other tools.
+ *
+ * The catalog includes:
+ * - All compiled types (complex types as interfaces)
+ * - Type aliases (simple types)
+ * - Operation definitions with input/output types
+ * - Metadata for XML serialization
+ * - Original compiler options
+ * - Service information from the WSDL
+ *
+ * @param {string} outFile - Path to the output JSON file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog to write
+ */
 export declare function emitCatalog(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=catalogEmitter.d.ts.map

package/dist/emit/catalogEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalogEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/catalogEmitter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAEnE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAOrE"}
+{"version":3,"file":"catalogEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/catalogEmitter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAOrE"}

package/dist/emit/catalogEmitter.js

@@ -1,4 +1,35 @@
+/**
+ * Catalog Emitter for TypeScript WSDL Client Generator
+ *
+ * This module is responsible for writing the complete compiled catalog to a JSON file,
+ * which serves as a structured representation of the WSDL for introspection and further
+ * processing. The catalog includes all types, operations, metadata, and compilation options,
+ * making it useful for:
+ *
+ * - Debugging the compilation process
+ * - Providing input for other tools (like OpenAPI generators)
+ * - Supporting runtime introspection of the service structure
+ * - Enabling incremental compilation workflows
+ */
 import fs from "node:fs";
+/**
+ * Emits the compiled catalog as a JSON file
+ *
+ * This function writes the complete compiled catalog to a JSON file, preserving all
+ * type definitions, operation information, and metadata in a structured format.
+ * The output is useful for introspection, debugging, and as input for other tools.
+ *
+ * The catalog includes:
+ * - All compiled types (complex types as interfaces)
+ * - Type aliases (simple types)
+ * - Operation definitions with input/output types
+ * - Metadata for XML serialization
+ * - Original compiler options
+ * - Service information from the WSDL
+ *
+ * @param {string} outFile - Path to the output JSON file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog to write
+ */
 export function emitCatalog(outFile, compiled) {
     try {
         fs.writeFileSync(outFile, JSON.stringify(compiled, null, 2), "utf8");

package/dist/emit/clientEmitter.d.ts

@@ -1,3 +1,20 @@
 import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+/**
+ * Generates a TypeScript SOAP client class from a compiled WSDL catalog
+ *
+ * This function creates a fully-typed TypeScript class that wraps the node-soap library
+ * with strongly-typed methods for each SOAP operation defined in the WSDL. The generated
+ * client handles XML serialization/deserialization, SOAP headers, and security settings.
+ *
+ * The client provides:
+ * - Async methods for each WSDL operation with proper TypeScript typing
+ * - A Response type that includes headers, raw XML, and typed response data
+ * - Security annotations based on WS-Policy analysis
+ * - Support for custom attribute keys and namespaces
+ * - Clean error handling with meaningful messages
+ *
+ * @param {string} outFile - Path to the output TypeScript file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ */
 export declare function emitClient(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=clientEmitter.d.ts.map

package/dist/emit/clientEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clientEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/clientEmitter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAGnE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAuWpE"}
+{"version":3,"file":"clientEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/clientEmitter.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAGnE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAuWpE"}

package/dist/emit/clientEmitter.js

@@ -1,6 +1,36 @@
-// noinspection UnreachableCodeJS,JSUnusedLocalSymbols
+/**
+ * TypeScript SOAP Client Emitter
+ *
+ * This module generates a strongly-typed TypeScript SOAP client class from the compiled WSDL catalog.
+ * The generated client wraps the node-soap library with type-safe operation methods and proper
+ * TypeScript declarations for request/response types.
+ *
+ * Key features of the generated client:
+ * - Type-safe operation methods matching WSDL operations
+ * - Response type that includes headers, raw XML, and typed data
+ * - Security hint annotations from WS-Policy
+ * - Support for custom attribute handling
+ * - Consistent error handling and client configuration
+ */
 import fs from "node:fs";
-import { pascal, deriveClientName, pascalToSnakeCase } from "../util/tools.js";
+import { deriveClientName, pascal, pascalToSnakeCase } from "../util/tools.js";
+/**
+ * Generates a TypeScript SOAP client class from a compiled WSDL catalog
+ *
+ * This function creates a fully-typed TypeScript class that wraps the node-soap library
+ * with strongly-typed methods for each SOAP operation defined in the WSDL. The generated
+ * client handles XML serialization/deserialization, SOAP headers, and security settings.
+ *
+ * The client provides:
+ * - Async methods for each WSDL operation with proper TypeScript typing
+ * - A Response type that includes headers, raw XML, and typed response data
+ * - Security annotations based on WS-Policy analysis
+ * - Support for custom attribute keys and namespaces
+ * - Clean error handling with meaningful messages
+ *
+ * @param {string} outFile - Path to the output TypeScript file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ */
 export function emitClient(outFile, compiled) {
     const isValidIdent = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
     const reserved = new Set([
@@ -52,7 +82,7 @@ export function emitClient(outFile, compiled) {
         methods.push(methodTemplate);
     }
     const methodsBody = methods.join("\n");
-    // noinspection JSFileReferences,JSUnresolvedReference,CommaExpressionJS,JSDuplicatedDeclaration,ReservedWordAsName,JSCommentMatchesSignature,JSValidateTypes,JSIgnoredPromiseFromCall,BadExpressionStatementJS,ES6UnusedImports,JSUnnecessarySemicolon
+    // noinspection JSFileReferences,JSUnresolvedReference,CommaExpressionJS,JSDuplicatedDeclaration,ReservedWordAsName,JSCommentMatchesSignature,JSValidateTypes,JSIgnoredPromiseFromCall,BadExpressionStatementJS,ES6UnusedImports,JSUnnecessarySemicolon,UnreachableCodeJS,JSUnusedLocalSymbols
     const classTemplate = `// noinspection JSAnnotator
 
 /**